# macrocosm-os/macrocosmos-mcp [Health: Active]

**Category:** 🌐 Social Media  
**Repository:** https://github.com/macrocosm-os/macrocosmos-mcp  
**GitHub Stars:** 29  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/macrocosm-os-macrocosmos-mcp

## Description
Access real-time X/Reddit/YouTube data directly in your LLM applications  with search phrases, users, and date filtering.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "macrocosmos-mcp": {
    "command": "uvx",
    "args": ["macrocosmos-mcp"],
    "env": {
      "MC_API": ""
    }
  }
}
```

**Requires environment variables:** `MC_API` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

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

_Full upstream README: https://allmcps.com/mcp/macrocosm-os-macrocosmos-mcp/readme_