Skip to main content
Glama
Macrocosmos MCP

Macrocosmos MCP

Official
by macrocosm-os

Macrocosmos MCP


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:

{
  "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

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:

{
  "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

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.

Parameters:

Parameter

Type

Description

crawler_id

string

REQUIRED. Get from get_gravity_task_status

max_rows

int

Max rows to include. Default: 10000

email

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

dataset_id

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

gravity_task_id

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

dataset_id

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 instantly

Large 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 file

Example 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 tools
build_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:

  1. Basic collection: create_gravity_task( tasks=[{"platform": "x", "topic": "#ai"}], name="AI Tweets" )

  2. With keyword filter: create_gravity_task( tasks=[{"platform": "x", "topic": "#Bittensor", "keyword": "dTAO"}], name="Bittensor dTAO mentions" )

  3. 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:

  1. Get recent tweets from specific users: query_on_demand_data(source='X', usernames=['@elonmusk', '@spacex'], limit=20)

  2. Search tweets by keywords in last 24 hours: query_on_demand_data(source='X', keywords=['AI', 'machine learning'], limit=30)

  3. Monitor specific users AND filter by keywords: query_on_demand_data(source='X', usernames=['@nasa'], keywords=['space', 'mars'], limit=20)

  4. Monitor Reddit subreddits: query_on_demand_data(source='REDDIT', keywords=['r/astronomy', 'space'], limit=50)

  5. 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)

  6. Strict keyword matching (requires ALL keywords): query_on_demand_data(source='X', keywords=['AI', 'machine learning'], keyword_mode='all', limit=30)

  7. 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

    A4.1/5.0

    Scored across 7 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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 npm
      11
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A 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
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      B
      maintenance
      Live 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 npm
      1
      MIT