crypto-sentiment-mcp

Instructions

Implementation Reference

• main.py:91-114 (handler)

  The main handler function for the 'get_social_volume' MCP tool. Decorated with @mcp.tool() for automatic registration. Fetches social volume data from Santiment API via the fetch_santiment_data helper, computes the total mentions by summing daily values, and returns a user-friendly formatted string.
  @mcp.tool() def get_social_volume(asset: str, days: int = 7) -> str: """ Retrieve the total social volume (social_volume_total) for a given asset. It calculates the total number of social data text documents that contain the given search term at least once. Examples of documents are telegram messages and reddit posts. Parameters: - asset (str): The cryptocurrency slug (e.g., "bitcoin", "ethereum"). Required. - days (int): Number of days to sum the social volume, defaults to 7. Usage: - Call this tool to get the total number of social media mentions for an asset over a period. Returns: - A string with the total social volume (e.g., "Bitcoin's social volume over the past 7 days is 15,000 mentions"). """ try: data = fetch_santiment_data("social_volume_total", asset, days) timeseries = data.get("data", {}).get("getMetric", {}).get("timeseriesData", []) if not timeseries: return f"Unable to fetch social volume for {asset}. Check subscription limits or asset availability." total_volume = sum(int(d["value"]) for d in timeseries) return f"{asset.capitalize()}'s social volume over the past {days} days is {total_volume:,} mentions." except Exception as e: return f"Error fetching social volume for {asset}: {str(e)}"
• main.py:16-42 (helper)

  Helper utility function used by get_social_volume (and other tools) to query the Santiment GraphQL API for timeseries data of a specific metric (e.g., 'social_volume_total') for a given asset over the past N days.
  def fetch_santiment_data(metric: str, asset: str, days: int) -> dict: now = datetime.now(UTC) to_date = now from_date = to_date - timedelta(days=days) query = f""" {{ getMetric(metric: "{metric}") {{ timeseriesData( slug: "{asset}" from: "{from_date.isoformat()}" to: "{to_date.isoformat()}" interval: "1d" ) {{ datetime value }} }} }} """ response = requests.post(SANTIMENT_API_URL, json={"query": query}, headers=HEADERS) result = response.json() if result.get("errors"): raise Exception(f"API error: {result.get('errors')}") return result