Macrocosmos MCP

What macrocosm-os/macrocosmos-mcp MCP server does

The macrocosm-os/macrocosmos-mcp MCP server exposes Macrocosmos social-data operations to MCP clients. It works with X (Twitter) and Reddit, allowing an agent to retrieve recent posts or start a longer-running collection workflow. The README identifies Data Universe (SN13) on Bittensor as the underlying source.

For quick requests, query_on_demand_data accepts a platform, usernames, keywords, ISO-formatted dates, a result limit, and an any or all keyword mode. X usernames may include or omit @. Reddit queries use the first keyword as the subreddit, and username filtering is not available for Reddit. On-demand requests support up to 1,000 results, with a default window of the previous 24 hours and a default limit of 10.

How it works

The macrocosm-os/macrocosmos-mcp MCP server has two distinct collection paths. On-demand queries return data for immediate analysis. For larger jobs, create_gravity_task starts a collection that can run for seven days and returns a task identifier. get_gravity_task_status reports progress, including crawler identifiers, record counts, and collected bytes.

A Gravity workflow can include X and Reddit task objects. X topics must begin with # or $; plain X keywords are rejected. After enough data is collected, build_dataset stops the crawler and creates a dataset, optionally limited by row count. get_dataset_status reports the build progress and supplies Parquet download URLs when the dataset is ready. Active Gravity tasks and dataset builds can be cancelled, while completed datasets can be purged through the cancellation tools.

Setup and configuration

The macrocosm-os/macrocosmos-mcp MCP server requires a Macrocosmos API key. The README directs users to the Macrocosmos account page to create one and states that a free tier begins with $5 in credits. Install uv, then configure the MCP client to run uvx macrocosmos-mcp.

For Claude Desktop, add a server entry to claude_desktop_config.json with uvx as the command, macrocosmos-mcp as its argument, and the API key in the MC_API environment variable. The key should replace the placeholder shown in the README rather than being copied literally.

Tools and capabilities

Available tools include:

• query_on_demand_data for filtered X or Reddit searches.
• create_gravity_task for large-scale, seven-day collection jobs.
• get_gravity_task_status for task and crawler progress.
• build_dataset for stopping a crawler and preparing collected rows.
• get_dataset_status for build progress and Parquet download links.
• cancel_gravity_task for stopping a running collection.
• cancel_dataset for cancelling a build or purging a completed dataset.

The server is documented as compatible with Claude Desktop, Cursor, Windsurf, OpenAI Agents, and other MCP clients. This listing only maps the named desktop clients to client compatibility fields.

Limitations and notes

The on-demand tool is intended for requests of up to 1,000 results. Gravity tasks are the documented option when more data is needed, but their collection period is seven days. Building a dataset before that period ends permanently stops and de-registers the crawler from the network, so build_dataset should be used only when collection can end.

Required fields vary by operation: on-demand queries need source, Gravity creation needs tasks, and status or build operations require identifiers returned by earlier calls. X Gravity topics must use hashtag or ticker syntax, while Reddit username filtering is unavailable. The provided material documents X and Reddit access; it does not document YouTube support.