Overview

The Crypto Sentiment MCP Server provides AI agents with structured cryptocurrency market-mood signals by querying Santiment’s aggregated social media and news datasets. It exposes a set of MCP-compatible tools that return sentiment balance, social volume, dominance metrics and trending terms so agents can incorporate real-time social context into decision logic, alerts or natural-language responses.

This server is useful for developers building AI assistants, trading agents, research dashboards or alerting systems that need a concise synthesis of social and news-driven signals for crypto assets. Instead of parsing raw feeds, agents call well-defined tools to get normalized metrics and trend detections derived from Santiment’s data.

Features

Sentiment balance (positive vs. negative) per asset over configurable windows
Social volume (mentions) and spike/drop detection relative to historical averages
Social dominance: percentage share of discussion an asset commands in crypto media
Trending words/terms ranked by score over a time window
Simple MCP toolset that returns numeric values and human-friendly summaries
Lightweight Python server compatible with MCP clients; configurable via environment variables

Installation / Configuration

Prerequisites:

Python 3.10+
Santiment API key (create at https://app.santiment.net/)

Clone and install:

git clone https://github.com/kukapay/crypto-sentiment-mcp.git
cd crypto-sentiment-mcp
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Run with an environment variable for the Santiment API key (example using uvicorn):

export SANTIMENT_API_KEY="your_api_key_here"
uvicorn main:app --host 127.0.0.1 --port 8000

Example MCP server configuration snippet (JSON) for an MCP-compatible client:

{
  "mcpServers": {
    "crypto-sentiment-mcp": {
      "command": "uvicorn",
      "args": ["--app-dir", "path/to/crypto-sentiment-mcp", "main:app", "--port", "8000"],
      "env": {
        "SANTIMENT_API_KEY": "your_api_key_here"
      }
    }
  }
}

Notes:

Respect Santiment rate limits and API usage tiers.
If running inside containers or orchestrators, map the environment variable accordingly.

Available Tools

The server exposes these primary tools for MCP clients:

Tool name	Purpose	Parameters
get_sentiment_balance	Average sentiment balance (positive minus negative bias) for an asset over the period	asset: str, days: int = 7
get_social_volume	Total social mentions for an asset over the period	asset: str, days: int = 7
alert_social_shift	Detects significant spikes or drops vs recent average	asset: str, threshold: float = 50.0, days: int = 7
get_trending_words	Returns top trending words across crypto discussions	days: int = 7, top_n: int = 5
get_social_dominance	Percent share of crypto media discussion for an asset	asset: str, days: int = 7

Each tool returns structured values and a short textual summary suitable for display or further agent processing.

Use Cases

Alerting agent: trigger notifications when alert_social_shift reports a spike above a configured threshold (e.g., >50%). Example: “Bitcoin social volume spiked 75% compared to the prior average — investigate news or whale activity.”
Research assistant: use get_trending_words to surface emerging narrative terms (e.g., “halving”, “layer2”, “rugpull”) and correlate them with on-chain metrics.
Trading bot context: include get_sentiment_balance and get_social_dominance alongside price and volume features to adjust position sizing when social mood turns strongly positive or negative.
Dashboard widget: display weekly social dominance and sentiment trend lines for a watchlist of assets; fetch via periodic MCP calls and store in a timeseries DB.

Concrete examples (natural-language ↔ tool output):

Input: “What’s Bitcoin’s sentiment balance for the last 7 days?”
- Output: numeric value (e.g., 12.5) plus short summary: “Bitcoin’s sentiment balance over the past 7 days is 12.5 (net positive).”
Input: “Top 3 trending crypto words in the past 3 days?”
- Output: list: [“halving”, “defi”, “liquidations”] with scores.

Tips & Troubleshooting

API key errors: confirm SANTIMENT_API_KEY is set and valid; check error messages from the Santiment API for rate-limit indicators.
Time windows: choose days parameter to match agent cadence (short windows for intraday monitoring, longer windows for weekly trend detection).
Normalization: social volume counts are raw mentions; use alert_social_shift to receive relative-change detection rather than raw numbers.
Logging: enable server logs to inspect queries and responses during integration testing.

License: MIT (see repository LICENSE file).

Crypto Sentiment MCP Server with Santiment Insights