macrocosm-os/macrocosmos-mcp

Official Macrocosmos Model Context Protocol (MCP) server that enables interaction with X (Twitter) and Reddit, powered by Data Universe (SN13) on Bittensor. This server allows MCP clients like Claude Desktop , Cursor , Windsurf , OpenAI Agents and others to fetch real-time social media data.
---
Quickstart with Claude Desktop
1. Get your API key from Macrocosmos. There is a free tier with $5 of credits to start.
2. Install uv (Python package manager), install with curl -LsSf https://astral.sh/uv/install.sh | sh or see the uv repo for additional install methods.
3. Go to Claude > Settings > Developer > Edit Config > claude_desktop_config.json to include the following:
---
Available Tools
1. query_on_demand_data - Real-time Social Media Queries
Fetch real-time data from X (Twitter) and Reddit. Best for quick queries up to 1000 results.
**Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| source | string | **REQUIRED**. Platform: 'X' or 'REDDIT' (case-sensitive) |
| usernames | list | Up to 5 usernames. For X: @ is optional. Not available for Reddit |
| keywords | list | Up to 5 keywords. For Reddit: first item is subreddit (e.g., 'r/MachineLearning') |
| start_date | string | ISO format (e.g., '2024-01-01T00:00:00Z'). Defaults to 24h ago |
| end_date | string | ISO format. Defaults to now |
| limit | int | Max results 1-1000. Default: 10 |
| keyword_mode | string | 'any' (default) or 'all' |
**Example prompts:**
- "What has @elonmusk been posting about today?"
- "Get me the latest posts from r/bittensor about dTAO"
- "Fetch 50 tweets about #AI from the last week"
---
2. create_gravity_task - Large-Scale Data Collection
Create a Gravity task for collecting large datasets over 7 days. Use this when you need more than 1000 results.
**Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| tasks | list | **REQUIRED**. List of task objects (see below) |
| name | string | Optional name for the task |
| email | string | Email for notification when complete |
**Task object structure:**
**Important:** For X (Twitter), topics MUST start with # or $ (e.g., #ai, $BTC). Plain keywords are rejected.
**Example prompts:**
- "Create a gravity task to collect #Bittensor tweets for the next 7 days"
- "Start collecting data from r/MachineLearning about neural networks"
---
3. get_gravity_task_status - Check Collection Progress
Monitor your Gravity task and see how much data has been collected.
**Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| gravity_task_id | string | **REQUIRED**. The task ID from create_gravity_task |
| include_crawlers | bool | Include detailed stats. Default: True |
**Returns:** Task status, crawler IDs, records_collected, bytes_collected
**Example prompts:**
- "Check the status of my Bittensor data collection task"
- "How many records have been collected so far?"
---
4. build_dataset - Build & Download Dataset
Build a dataset from collected data before the 7-day completion.
**Warning:** This will STOP the crawler and de-register it from the network.