# Twitter MCP 数据服务

`MCP` `Twitter` `AI工具` `实时监控` `推文搜索`

<p align="center">
  <b>Twitter MCP 服务器</b><br>
  Twitter/X 数据 · 用户资料 · 推文搜索 · 关注者事件 · KOL 追踪
</p>

---

## 快速安装

> **首先，前往 [https://6551.io/mcp](https://6551.io/mcp) 获取您的 API Token。**

### Claude Code

```bash
claude mcp add twitter \
  -e TWITTER_TOKEN=<your-token> \
  -- uv --directory /path/to/twitter-mcp run twitter-mcp
```

> 将 `/path/to/twitter-mcp` 替换为本地项目路径，将 `<your-token>` 替换为您的 Token。

### OpenClaw

```bash
export TWITTER_TOKEN="<your-token>"
cp -r openclaw-skill/opentwitter ~/.openclaw/skills/
```

---

## 让 AI 帮你审查并安装

不确定这个 MCP 是否安全？将以下提示词发送给您的 AI 助手——它会先审查源码，确认安全后再安装：

> **复制以下提示词发送给您的 AI 助手（将 `<project-path>` 和 `<your-token>` 替换为实际值）：**

```text
请帮我审查并安装 twitter-mcp MCP 服务器。项目路径为 <project-path>。

步骤：
1. 审查以下文件的安全性：
   - src/twitter_mcp/api_client.py — 确认只连接 ai.6551.io，不向其他地方发送数据
   - src/twitter_mcp/config.py — 确认 Token 只从本地 config.json 或环境变量读取，无硬编码密钥或泄露
   - src/twitter_mcp/tools.py — 确认所有工具只执行 API 查询，不写文件、不执行命令、不含危险操作
   - pyproject.toml — 确认依赖只有 mcp、httpx，无可疑包
2. 告知结论：安全 / 有风险 / 有问题，并说明具体原因
3. 如果安全，执行安装（Token 从 https://6551.io/mcp 获取）：
   claude mcp add twitter -e TWITTER_TOKEN=<your-token> -- uv --directory <project-path> run twitter-mcp
```

---

## 能做什么？

连接后，直接向 AI 助手提问：

| 你说 | 它做 |
|------|------|
| "显示 @elonmusk 的 Twitter 资料" | 获取用户资料信息 |
| "查看 @VitalikButerin 最近发了什么推文" | 获取用户最新推文 |
| "搜索比特币相关推文" | 关键词搜索 |
| "查找带 #crypto 话题标签的推文" | 话题标签搜索 |
| "获赞超过 1000 的 ETH 相关热门推文" | 带互动量过滤的搜索 |
| "谁引用了这条推文" | 获取指定推文的引用推文 |
| "谁转发了这条推文" | 获取转发该推文的用户 |
| "最近谁关注了 @elonmusk" | 获取新增关注者事件 |
| "谁取关了 @elonmusk" | 获取取消关注事件 |
| "@elonmusk 删除了哪些推文" | 获取已删除的推文 |
| "哪些 KOL 关注了 @elonmusk" | 获取 KOL 关注者 |

---

## 可用工具

| 工具 | 描述 |
|------|------|
| `get_twitter_user` | 通过用户名获取用户资料 |
| `get_twitter_user_by_id` | 通过数字 ID 获取用户资料 |
| `get_twitter_user_tweets` | 获取用户最近的推文 |
| `search_twitter` | 基础过滤条件搜索推文 |
| `search_twitter_advanced` | 多条件高级搜索 |
| `get_twitter_follower_events` | 获取关注/取关事件 |
| `get_twitter_deleted_tweets` | 获取用户已删除的推文 |
| `get_twitter_kol_followers` | 获取 KOL（关键意见领袖）关注者 |
| `get_twitter_article_by_id` | 通过 ID 获取 Twitter 文章 |
| `get_twitter_tweet_by_id` | 通过 ID 获取推文（含嵌套回复/引用） |
| `get_twitter_quote_tweets_by_id` | 获取引用指定推文的所有推文 |
| `get_twitter_retweet_users_by_id` | 获取转发指定推文的用户 |
| `get_twitter_watch` | 获取所有 Twitter 监控用户 |
| `add_twitter_watch` | 添加 Twitter 用户到监控列表 |
| `delete_twitter_watch` | 从监控列表中按用户名删除用户 |

---

## 配置

### 获取 API Token

前往 [https://6551.io/mcp](https://6551.io/mcp) 获取您的 API Token。

设置环境变量：

```bash
# macOS / Linux
export TWITTER_TOKEN="<your-token>"

# Windows PowerShell
$env:TWITTER_TOKEN = "<your-token>"
```

| 变量 | 必填 | 描述 |
|------|------|------|
| `TWITTER_TOKEN` | **是** | 6551 API Bearer Token（从 https://6551.io/mcp 获取） |
| `TWITTER_API_BASE` | 否 | 覆盖 REST API 地址 |
| `TWITTER_MAX_ROWS` | 否 | 每次查询的最大结果数（默认：100） |

也支持在项目根目录下放置 `config.json`（环境变量优先级更高）：

```json
{
  "api_base_url": "https://ai.6551.io",
  "api_token": "<your-token>",
  "max_rows": 100
}
```

---

## WebSocket 实时订阅

**端点**：`wss://ai.6551.io/open/twitter_wss?token=YOUR_TOKEN`

订阅您监控的 Twitter 账号的实时事件。

### 订阅 Twitter 事件

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "twitter.subscribe"
}
```

**响应**：
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "success": true
  }
}
```

### 取消订阅

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "twitter.unsubscribe"
}
```

### 服务器推送 - Twitter 事件

当监控账号有动态时，服务器推送：

```json
{
  "jsonrpc": "2.0",
  "method": "twitter.event",
  "params": {
    "id": 123456,
    "twAccount": "elonmusk",
    "twUserName": "Elon Musk",
    "profileUrl": "https://twitter.com/elonmusk",
    "eventType": "NEW_TWEET",
    "content": "...",
    "ca": "0x1234...",
    "remark": "自定义备注",
    "createdAt": "2026-03-06T10:00:00Z"
  }
}
```

**注意**：`content` 字段的结构因事件类型而异（见下文）。

**事件类型及内容结构**：

#### 推文事件
- `NEW_TWEET` - 发布新推文
- `NEW_TWEET_REPLY` - 发布回复推文
- `NEW_TWEET_QUOTE` - 发布引用推文
- `NEW_RETWEET` - 转发推文
- `CA` - 含 CA 地址的推文

推文事件的内容结构：
```json
{
  "id": "1234567890",
  "text": "推文内容...",
  "createdAt": "2026-03-06T10:00:00Z",
  "language": "en",
  "retweetCount": 100,
  "favoriteCount": 500,
  "replyCount": 20,
  "quoteCount": 10,
  "viewCount": 10000,
  "userScreenName": "elonmusk",
  "userName": "Elon Musk",
  "userIdStr": "44196397",
  "userFollowers": 170000000,
  "userVerified": true,
  "conversationId": "1234567890",
  "isReply": false,
  "isQuote": false,
  "hashtags": ["crypto", "bitcoin"],
  "media": [
    {
      "type": "photo",
      "url": "https://...",
      "thumbUrl": "https://..."
    }
  ],
  "urls": [
    {
      "url": "https://...",
      "expandedUrl": "https://...",
      "displayUrl": "example.com"
    }
  ],
  "mentions": [
    {
      "username": "VitalikButerin",
      "name": "Vitalik Buterin"
    }
  ]
}
```

#### 关注者事件
- `NEW_FOLLOWER` - 新增关注者
- `NEW_UNFOLLOWER` - 取消关注事件

关注者事件的内容结构（数组）：
```json
[
  {
    "id": 123,
    "twId": 44196397,
    "twAccount": "elonmusk",
    "twUserName": "Elon Musk",
    "twUserLabel": "Verified",
    "description": "用户简介...",
    "profileUrl": "https://...",
    "bannerUrl": "https://...",
    "followerCount": 170000000,
    "friendCount": 500,
    "createdAt": "2026-03-06T10:00:00Z"
  }
]
```

#### 资料更新事件
- `UPDATE_NAME` - 用户名变更（内容：新用户名字符串）
- `UPDATE_DESCRIPTION` - 简介更新（内容：新简介字符串）
- `UPDATE_AVATAR` - 头像变更（内容：新头像 URL 字符串）
- `UPDATE_BANNER` - 横幅图片变更（内容：新横幅 URL 字符串）

#### 其他事件
- `TWEET_TOPPING` - 推文置顶
- `DELETE` - 推文删除
- `SYSTEM` - 系统事件
- `TRANSLATE` - 推文翻译
- `CA_CREATE` - CA 代币创建

---

## 数据结构

### Twitter 用户

```json
{
  "userId": "44196397",
  "screenName": "elonmusk",
  "name": "Elon Musk",
  "description": "...",
  "followersCount": 170000000,
  "friendsCount": 500,
  "statusesCount": 30000,
  "verified": true
}
```

### 推文

```json
{
  "id": "1234567890",
  "text": "推文内容...",
  "createdAt": "2024-02-20T12:00:00Z",
  "retweetCount": 1000,
  "favoriteCount": 5000,
  "replyCount": 200,
  "userScreenName": "elonmusk",
  "hashtags": ["crypto", "bitcoin"],
  "urls": [{"url": "https://..."}]
}
```

---

<details>
<summary><b>其他客户端 — 手动安装</b>（点击展开）</summary>

> 以下所有配置中，将 `/path/to/twitter-mcp` 替换为本地项目实际路径，将 `<your-token>` 替换为从 [https://6551.io/mcp](https://6551.io/mcp) 获取的 Token。

### Claude Desktop

编辑配置文件（macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`，Windows：`%APPDATA%\Claude\claude_desktop_config.json`）：

```json
{
  "mcpServers": {
    "twitter": {
      "command": "uv",
      "args": ["--directory", "/path/to/twitter-mcp", "run", "twitter-mcp"],
      "env": {
        "TWITTER_TOKEN": "<your-token>"
      }
    }
  }
}
```

### Cursor

`~/.cursor/mcp.json` 或 设置 > MCP Servers：

```json
{
  "mcpServers": {
    "twitter": {
      "command": "uv",
      "args": ["--directory", "/path/to/twitter-mcp", "run", "twitter-mcp"],
      "env": {
        "TWITTER_TOKEN": "<your-token>"
      }
    }
  }
}
```

### Windsurf

`~/.codeium/windsurf/mcp_config.json`：

```json
{
  "mcpServers": {
    "twitter": {
      "command": "uv",
      "args": ["--directory", "/path/to/twitter-mcp", "run", "twitter-mcp"],
      "env": {
        "TWITTER_TOKEN": "<your-token>"
      }
    }
  }
}
```

### Cline

VS Code 侧边栏 > Cline > MCP Servers > Configure，编辑 `cline_mcp_settings.json`：

```json
{
  "mcpServers": {
    "twitter": {
      "command": "uv",
      "args": ["--directory", "/path/to/twitter-mcp", "run", "twitter-mcp"],
      "env": {
        "TWITTER_TOKEN": "<your-token>"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

### Continue.dev

`~/.continue/config.yaml`：

```yaml
mcpServers:
  - name: twitter
    command: uv
    args:
      - --directory
      - /path/to/twitter-mcp
      - run
      - twitter-mcp
    env:
      TWITTER_TOKEN: <your-token>
```

### Cherry Studio

设置 > MCP Servers > 添加 > 类型选 stdio：命令填 `uv`，参数填 `--directory /path/to/twitter-mcp run twitter-mcp`，环境变量填 `TWITTER_TOKEN`。

### Zed 编辑器

`~/.config/zed/settings.json`：

```json
{
  "context_servers": {
    "twitter": {
      "command": {
        "path": "uv",
        "args": ["--directory", "/path/to/twitter-mcp", "run", "twitter-mcp"],
        "env": {
          "TWITTER_TOKEN": "<your-token>"
        }
      }
    }
  }
}
```

### 任意 stdio MCP 客户端

```bash
TWITTER_TOKEN=<your-token> \
  uv --directory /path/to/twitter-mcp run twitter-mcp
```

</details>

---

## 兼容性

| 客户端 | 安装方式 | 状态 |
|--------|----------|------|
| **Claude Code** | `claude mcp add` | 一行命令 |
| **OpenClaw** | 复制 skill 目录 | 一行命令 |
| Claude Desktop | JSON 配置 | 已支持 |
| Cursor | JSON 配置 | 已支持 |
| Windsurf | JSON 配置 | 已支持 |
| Cline | JSON 配置 | 已支持 |
| Continue.dev | YAML / JSON | 已支持 |
| Cherry Studio | 图形界面 | 已支持 |
| Zed | JSON 配置 | 已支持 |

---

## 开发

```bash
cd /path/to/twitter-mcp
uv sync
uv run twitter-mcp
```

```bash
# MCP Inspector
npx @modelcontextprotocol/inspector uv --directory /path/to/twitter-mcp run twitter-mcp
```

### 项目结构

```
├── README.md
├── docs/
│   ├── README_JA.md           # 日本語
│   └── README_KO.md           # 한국어
├── openclaw-skill/opentwitter/    # OpenClaw Skill
├── pyproject.toml
├── config.json
└── src/twitter_mcp/
    ├── server.py              # 入口点
    ├── app.py                 # FastMCP 实例
    ├── config.py              # 配置加载器
    ├── api_client.py          # HTTP 客户端
    └── tools.py               # 8 个工具
```

## 许可证

MIT