macrocosm-os/macrocosmos-mcp

Macrocosmos MCP

<p align="center">
官方 Macrocosmos <a href="https://github.com/modelcontextprotocol">Model Context Protocol (MCP)</a> 服务器，由 Bittensor 上的 Data Universe (SN13) 提供支持，可实现与 X (Twitter) 和 Reddit 的交互。该服务器允许 <a href="https://www.anthropic.com/claude">Claude Desktop</a>, <a href="https://www.cursor.so">Cursor</a>, <a href="https://codeium.com/windsurf">Windsurf</a>, <a href="https://github.com/openai/openai-agents-python">OpenAI Agents</a> 等 MCP 客户端获取实时社交媒体数据。
</p>

---

Claude Desktop 快速上手

1. 从 Macrocosmos 获取你的 API key。提供 5 美元额度的免费层级供开始使用。
2. 安装 uv (Python 包管理器)，使用 curl -LsSf https://astral.sh/uv/install.sh | sh 安装，或参阅 uv repo 查看其他安装方法。
3. 前往 Claude > Settings > Developer > Edit Config > claude_desktop_config.json 并添加以下内容：

{
  "mcpServers": {
    "macrocosmos": {
      "command": "uvx",
      "args": ["macrocosmos-mcp"],
      "env": {
        "MC_API": "<insert-your-api-key-here>"
      }
    }
  }
}

可用工具

1. query_on_demand_data - 实时社交媒体查询

从 X (Twitter) 和 Reddit 获取实时数据。适用于最多 1000 条结果的快速查询。

参数：
| 参数 | 类型 | 描述 |
|-----------|------|-------------|
| source | string | 必填。平台：'X' 或 'REDDIT'（区分大小写） |
| usernames | list | 最多 5 个用户名。对于 X：@ 为可选。Reddit 不支持此参数 |
| keywords | list | 最多 5 个关键词。对于 Reddit：第一个项目为 subreddit（例如 'r/MachineLearning'） |
| start_date | string | ISO 格式（例如 '2024-01-01T00:00:00Z'）。默认为 24 小时前 |
| end_date | string | ISO 格式。默认为当前时间 |
| limit | int | 最大结果数 1-1000。默认值：10 |
| keyword_mode | string | 'any'（默认）或 'all' |

提示词示例：

• "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 - 大规模数据采集

创建一个 Gravity 任务，用于在 7 天内采集大规模数据集。当你需要超过 1000 条结果时请使用此工具。

参数：
| 参数 | 类型 | 描述 |
|-----------|------|-------------|
| tasks | list | 必填。任务对象列表（见下文） |
| name | string | 任务的可选名称 |
| email | string | 完成后的通知邮箱 |

Task 对象结构：

{
  "platform": "x",           // 'x' or 'reddit'
  "topic": "#Bittensor",     // For X: MUST start with '#' or '$'
  "keyword": "dTAO"          // Optional: filter within topic
}

提示词示例：

• "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 - 检查采集进度

监控您的 Gravity 任务并查看已采集的数据量。

参数：
| 参数 | 类型 | 描述 |
|-----------|------|-------------|
| gravity_task_id | string | 必填。来自 create_gravity_task 的任务 ID |
| include_crawlers | bool | 是否包含详细统计信息。默认值：True |

返回值： Task status, crawler IDs, records_collected, bytes_collected

提示词示例：

• "Check the status of my Bittensor data collection task"

• "How many records have been collected so far?"

---

4. build_dataset - 构建并下载数据集

在 7 天期限完成前，利用已采集的数据构建数据集。

警告： 此操作将停止 crawler 并将其从网络中注销。

参数：
| 参数 | 类型 | 描述 |
|-----------|------|-------------|
| crawler_id | string | 必填。通过 get_gravity_task_status 获取 |
| max_rows | int | 最大包含行数。默认值：10000 |
| email | string | 准备就绪后的通知邮箱 |

提示词示例：

• "Build a dataset from my Bittensor crawler with 5000 rows"

• "I have enough data, build the dataset now"

---### 5. get_dataset_status - 检查构建进度与下载

检查数据集构建进度，并在就绪时获取下载链接。

参数：
| 参数 | 类型 | 描述 |
|-----------|------|-------------|
| dataset_id | string | 必填。来自 build_dataset 的数据集 ID |

返回值： 构建状态（共 10 个步骤）；完成后返回 Parquet 文件的下载 URL

示例提示词：

• "我的数据集可以下载了吗？"

• "获取我的 Bittensor 数据集的下载链接"

---

6. cancel_gravity_task - 停止数据采集

取消正在运行的 Gravity 任务。

参数：
| 参数 | 类型 | 描述 |
|-----------|------|-------------|
| gravity_task_id | string | 必填。要取消的任务 ID |

---

7. cancel_dataset - 取消构建或清除数据集

取消数据集构建或清除已完成的数据集。

参数：
| 参数 | 类型 | 描述 |
|-----------|------|-------------|
| dataset_id | string | 必填。要取消/清除的数据集 ID |

---

示例工作流

快速查询（按需）

code

User: "What's the sentiment about $TAO on Twitter today?"