Macrocosmos MCP
OfficialProvides tools for querying real-time Reddit data (posts from subreddits and keywords) and creating large-scale data collection tasks for Reddit content.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Macrocosmos MCP Fetch 10 tweets about #AI from the last week"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Macrocosmos MCP
Quickstart with Claude Desktop
Get your API key from Macrocosmos. There is a free tier with $5 of credits to start.
Install
uv(Python package manager), install withcurl -LsSf https://astral.sh/uv/install.sh | shor see theuvrepo for additional install methods.Go to Claude > Settings > Developer > Edit Config > claude_desktop_config.json to include the following:
{
"mcpServers": {
"macrocosmos": {
"command": "uvx",
"args": ["macrocosmos-mcp"],
"env": {
"MC_API": "<insert-your-api-key-here>"
}
}
}
}Related MCP server: SocialData MCP Server
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 |
| string | REQUIRED. Platform: |
| list | Up to 5 usernames. For X: |
| list | Up to 5 keywords. For Reddit: first item is subreddit (e.g., |
| string | ISO format (e.g., |
| string | ISO format. Defaults to now |
| int | Max results 1-1000. Default: 10 |
| string |
|
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 |
| list | REQUIRED. List of task objects (see below) |
| string | Optional name for the task |
| string | Email for notification when complete |
Task object structure:
{
"platform": "x", // 'x' or 'reddit'
"topic": "#Bittensor", // For X: MUST start with '#' or '$'
"keyword": "dTAO" // Optional: filter within topic
}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 |
| string | REQUIRED. The task ID from create_gravity_task |
| bool | Include detailed stats. Default: |
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.
Parameters:
Parameter | Type | Description |
| string | REQUIRED. Get from get_gravity_task_status |
| int | Max rows to include. Default: 10000 |
| string | Email for notification when ready |
Example prompts:
"Build a dataset from my Bittensor crawler with 5000 rows"
"I have enough data, build the dataset now"
5. get_dataset_status - Check Build Progress & Download
Check dataset build progress and get download links when ready.
Parameters:
Parameter | Type | Description |
| string | REQUIRED. The dataset ID from build_dataset |
Returns: Build status (10 steps), and when complete: download URLs for Parquet files
Example prompts:
"Is my dataset ready to download?"
"Get the download link for my Bittensor dataset"
6. cancel_gravity_task - Stop Data Collection
Cancel a running Gravity task.
Parameters:
Parameter | Type | Description |
| string | REQUIRED. The task ID to cancel |
7. cancel_dataset - Cancel Build or Purge Dataset
Cancel a dataset build or purge a completed dataset.
Parameters:
Parameter | Type | Description |
| string | REQUIRED. The dataset ID to cancel/purge |
Example Workflows
Quick Query (On-Demand)
User: "What's the sentiment about $TAO on Twitter today?"
→ Uses query_on_demand_data to fetch recent tweets
→ Returns up to 1000 results instantlyLarge Dataset Collection (Gravity)
User: "I need to collect a week's worth of #AI tweets for analysis"
1. create_gravity_task → Returns gravity_task_id
2. get_gravity_task_status → Monitor progress, get crawler_ids
3. build_dataset → When ready, build the dataset
4. get_dataset_status → Get download URL for Parquet fileExample Prompts
On-Demand Queries
"What has the president of the U.S. been saying over the past week on X?"
"Fetch me information about what people are posting on r/politics today."
"Please analyze posts from @elonmusk for the last week."
"Get me 100 tweets about #Bittensor and analyze the sentiment"
Large-Scale Collection
"Create a gravity task to collect data about #AI from Twitter and r/MachineLearning from Reddit"
"Start a 7-day collection of $BTC tweets with keyword 'ETF'"
"Check how many records my gravity task has collected"
"Build a dataset with 10,000 rows from my crawler"
MIT License Made with love by the Macrocosmos team
Available Tools
7 toolsbuild_datasetA
Build a dataset from collected data before the 7-day task completion. Use this when you have enough data and don't want to wait for the full collection period.
WARNING: Building a dataset will STOP the crawler and de-register it from the network. The crawler will no longer collect new data after this operation.
Parameters:
crawler_id (str, REQUIRED): The ID of the crawler to build dataset from (Get this from get_gravity_task_status response - look for 'crawler_ids' field)
max_rows (int, default: 10000): Maximum number of rows to include in the dataset
email (str, optional): Email address for notification when dataset is ready
redirect_url (str, optional): URL to redirect to from the email notification
Returns:
dataset_id: Unique identifier to track the dataset build
Build status and progress information (10 steps total)
Example: build_dataset( crawler_id="crawler-0-multicrawler-9f518ae4-xxxx", max_rows=10000, email="user@example.com" )
Inputs: crawler_id (required), email, max_rows, redirect_url. Returns: result
cancel_datasetB
Cancel a dataset build or purge a completed dataset.
Parameters:
dataset_id (str, REQUIRED): The ID of the dataset to cancel/purge
Returns:
Success or error message
Example: cancel_dataset(dataset_id="dataset-71e97cfa-xxxx-xxxx-xxxx-33cd91be9028")
Inputs: dataset_id (required). Returns: result
cancel_gravity_taskA
Cancel a running Gravity task and stop data collection.
Parameters:
gravity_task_id (str, REQUIRED): The ID of the gravity task to cancel
Returns:
Success or error message
Example: cancel_gravity_task(gravity_task_id="multicrawler-9f518ae4-xxxx-xxxx-xxxx-8b73d7cd4c49")
Inputs: gravity_task_id (required). Returns: result
create_gravity_taskA
Create a Gravity task for large-scale data collection from X (Twitter) or Reddit. Use this for collecting large datasets over time (up to 7 days). For quick queries (up to 1000 results), use query_on_demand_data instead.
The task registers on the network within 20 minutes and collects data for 7 days. You'll receive an email notification when the dataset is ready for download.
Parameters:
tasks (List[dict], REQUIRED): List of task objects, each containing:
platform (str): 'x' or 'reddit'
topic (str): The hashtag/subreddit to monitor
For X: MUST start with '#' or '$' (e.g., '#ai', '$BTC') - plain keywords are rejected!
For Reddit: subreddit name (e.g., 'r/MachineLearning')
keyword (str, optional): Additional keyword filter within the topic
Filters posts to only those containing this keyword
Example: topic='#Bittensor', keyword='dTAO' -> only #Bittensor posts mentioning 'dTAO'
name (str, optional): Name for the task (helps organize multiple tasks)
email (str, optional): Email address for notification when dataset is ready
redirect_url (str, optional): URL to redirect to from the email notification
Returns:
gravity_task_id: Unique identifier to track and manage the task
Examples:
Basic collection: create_gravity_task( tasks=[{"platform": "x", "topic": "#ai"}], name="AI Tweets" )
With keyword filter: create_gravity_task( tasks=[{"platform": "x", "topic": "#Bittensor", "keyword": "dTAO"}], name="Bittensor dTAO mentions" )
Multiple platforms: create_gravity_task( tasks=[ {"platform": "x", "topic": "#ai", "keyword": "LLM"}, {"platform": "reddit", "topic": "r/MachineLearning"} ], name="AI Data Collection", email="user@example.com" )
Inputs: tasks (required), name, email, redirect_url. Returns: result
get_dataset_statusA
Get the status of a dataset build and download links when ready.
Parameters:
dataset_id (str, REQUIRED): The ID of the dataset to check
Returns:
Build status (Running, Completed, etc.)
Progress steps (10 total steps)
When completed: Download URLs for Parquet files
File metadata (size, row count, expiration date)
Example: get_dataset_status(dataset_id="dataset-71e97cfa-xxxx-xxxx-xxxx-33cd91be9028")
Inputs: dataset_id (required). Returns: result
get_gravity_task_statusA
Get the status of a Gravity task and see how much data has been collected.
Parameters:
gravity_task_id (str, REQUIRED): The ID of the gravity task to check
include_crawlers (bool, default: True): Whether to include detailed crawler information Set to True to see records_collected and bytes_collected for each crawler
Returns:
Task status (Running, Completed, Pending, etc.)
Task name and start time
List of crawler IDs (needed for build_dataset)
When include_crawlers=True: records_collected, bytes_collected per crawler
Example: get_gravity_task_status(gravity_task_id="multicrawler-9f518ae4-xxxx-xxxx-xxxx-8b73d7cd4c49")
Inputs: gravity_task_id (required), include_crawlers. Returns: result
query_on_demand_dataA
Fetch real-time social media data from X (Twitter) and Reddit through the Macrocosmos SN13 network. IMPORTANT: This tool requires 'source' parameter to be either 'X' or 'REDDIT' (case-sensitive). Parameters:
source (str, REQUIRED): Data platform - must be 'X' or 'REDDIT'
usernames (List[str], optional): Up to 5 usernames to monitor.
For X: '@' symbol is optional (e.g., ['elonmusk', '@spacex'] both work)
NOT available for Reddit
keywords (List[str], optional): Up to 5 keywords/hashtags to search
For X: any keywords or hashtags (e.g., ['AI', 'crypto', '#bitcoin'])
For Reddit: subreddit names (e.g., ['r/astronomy', 'space']) or 'r/all' for all subreddits
start_date (str, optional): Start date/datetime in YYYY-MM-DD or ISO format
Examples: '2024-04-01' or '2024-01-01T00:00:00Z'
Defaults to 24 hours ago from current time if not specified
end_date (str, optional): End date/datetime in YYYY-MM-DD or ISO format
Examples: '2024-04-25' or '2024-06-03T23:59:59Z'
Defaults to current time if not specified
limit (int, optional): Maximum number of results to return (range: 1-1000, default: 10)
keyword_mode (str, optional): How to match keywords - 'any' (default) or 'all'
'any': returns posts matching ANY of the keywords
'all': returns posts matching ALL of the keywords Default Behavior (when dates not specified): The tool searches the last 24 hours (from current time back to 24 hours ago). Usage Examples:
Get recent tweets from specific users: query_on_demand_data(source='X', usernames=['@elonmusk', '@spacex'], limit=20)
Search tweets by keywords in last 24 hours: query_on_demand_data(source='X', keywords=['AI', 'machine learning'], limit=30)
Monitor specific users AND filter by keywords: query_on_demand_data(source='X', usernames=['@nasa'], keywords=['space', 'mars'], limit=20)
Monitor Reddit subreddits: query_on_demand_data(source='REDDIT', keywords=['r/astronomy', 'space'], limit=50)
Search across all of Reddit with date range: query_on_demand_data(source='REDDIT', keywords=['r/all', 'space'], start_date='2025-04-01', end_date='2025-04-02', limit=50)
Strict keyword matching (requires ALL keywords): query_on_demand_data(source='X', keywords=['AI', 'machine learning'], keyword_mode='all', limit=30)
Precise datetime range search: query_on_demand_data(source='X', keywords=['Bitcoin'], start_date='2024-06-01T00:00:00Z', end_date='2024-06-03T23:59:59Z', limit=100)
Returns: JSON object containing:
status: "success" or error information
data: Array of posts/tweets with full content, user information, engagement metrics, timestamps, platform-specific metadata, and media attachments
meta: Processing statistics (miners queried, response rates, items returned, etc.) Platform-Specific Notes:
X (Twitter): '@' symbol is optional for usernames
Reddit: Does NOT support username filtering, only subreddit/keyword searches
All timestamps returned in UTC format
Inputs: source (required), limit, end_date, keywords, +3 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Most tools target distinct resources and actions clearly: on-demand query vs. Gravity task creation are separated by scale and use case, and status/cancel tools are split by resource type. The only mild ambiguity is between query_on_demand_data and create_gravity_task, but their descriptions explicitly clarify quick vs. large-scale collection.
All tools follow a consistent verb_noun snake_case pattern (query_, create_, get_, build_, cancel_). The naming clearly indicates the action and the target resource, making the API predictable and easy to navigate.
Seven tools is well-scoped for the two core workflows: on-demand queries and long-running Gravity data collection with dataset building. Each tool serves a distinct step in the lifecycle without redundancy or bloat.
The core lifecycle is covered: query, create task, check status, build dataset, check status, and cancel either operation. Minor gaps exist such as no listing of existing tasks/datasets and no way to retrieve a completed Gravity dataset directly without building it, but these are workable.
Maintenance
Related MCP Connectors
Live Reddit and X (Twitter) data: search, threads, users, subreddits, leads and mentions.
Twitter/X, Instagram, Reddit & TikTok data for AI agents. Billions of posts. No API keys.
Reddit & X data for AI agents over MCP. Semantic search, hosted, no Reddit API.
Scrape X, Reddit, LinkedIn, GitHub, Instagram and TikTok data as tools for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that enables AI models and applications to interact directly with Twitter/X, providing capabilities to create posts, reply to tweets, retrieve user data, and manage account actions.18 npm11MIT
- FlicenseNot gradedqualityDmaintenanceA comprehensive Model Context Protocol (MCP) server that provides tools for interacting with the SocialData API. This server allows you to fetch Twitter/X data, monitor user activity, and analyze social media engagement programmatically.7-

prowlo-mcpofficial
AlicenseNot gradedqualityBmaintenanceEnables AI agents to semantically search and access read-only Reddit and X data through a hosted MCP server, with residential proxy crawling and no API credentials required.MIT- AlicenseNot gradedqualityBmaintenanceLive X/Twitter search and AI trend digests without an API key, charging per call in USDC via x402. Enables real-time tweet search and AI summaries inside MCP clients.59 npm1MIT