X MCP

🚀 x-mcp

x-mcp 是一个 MCP（模型上下文协议）服务器，它能让 AI 代理全面访问 X（原 Twitter）API。通过自然语言，你可以实现发布推文、搜索、查看时间线、点赞、转发、上传媒体等操作。

该项目可与 Claude Code、Claude Desktop、OpenAI Codex、Cursor、Windsurf、Cline 以及其他任何支持 MCP 的客户端配合使用。

如果你是一个大语言模型/AI 代理，正在帮助用户设置此项目，请阅读 以获取可逐步指导用户完成设置的说明。

🚀 快速开始

🔍 功能概述

该项目支持使用推文的 URL 或 ID，你可以粘贴 https://x.com/user/status/123 或仅输入 123。

📦 安装指南

1. 克隆并构建项目

git clone https://github.com/INFATOSHI/x-mcp.git
cd x-mcp
npm install
npm run build

2. 获取 X API 凭证

你需要从 X 开发者门户 获取 5 个凭证，以下是具体获取步骤：

a) 创建应用

1. 访问 X 开发者门户。
2. 使用你的 X 账户登录。
3. 点击左侧侧边栏中的 应用。
4. 点击 创建应用（你可能需要先注册开发者账户）。
5. 为应用命名（例如 my-x-mcp）。
6. 你将立即看到 消费者密钥（API 密钥）、密钥（API 密钥密钥）和 Bearer 令牌。
7. 立即保存这三个凭证，因为密钥不会再次显示。

b) 启用写入权限

默认情况下，新应用仅具有读取权限。若要发布推文、点赞、转发等操作，你需要读取和写入权限。

1. 在应用页面中，向下滚动到 用户身份验证设置。
2. 点击 设置。
3. 将 应用权限 设置为 读取和写入。
4. 将 应用类型 设置为 Web 应用、自动化应用或机器人。
5. 将 回调 URI / 重定向 URL 设置为 https://localhost（必需但不会使用）。
6. 将 网站 URL 设置为任何有效的 URL（例如 https://x.com）。
7. 点击 保存。

c) 生成访问令牌（具有写入权限）

启用写入权限后，你需要生成（或重新生成）访问令牌和密钥，以便它们包含新的权限：

1. 返回应用的 密钥和令牌 页面。
2. 在 访问令牌和密钥 下，点击 重新生成。
3. 保存 访问令牌 和 访问令牌密钥。

如果你在生成令牌之前跳过了步骤 (b)，你的令牌将仅具有读取权限，发布操作将返回 403 错误。

3. 配置凭证

复制示例环境文件并填写你的 5 个凭证：

cp .env.example .env

编辑 .env 文件：

X_API_KEY=your_consumer_key
X_API_SECRET=your_secret_key
X_BEARER_TOKEN=your_bearer_token
X_ACCESS_TOKEN=your_access_token
X_ACCESS_TOKEN_SECRET=your_access_token_secret

💻 连接到客户端

选择以下客户端之一进行连接，你只需遵循其中一个部分的说明。

Claude Code

claude mcp add --scope user x-twitter -- node /ABSOLUTE/PATH/TO/x-mcp/dist/index.js

将 /ABSOLUTE/PATH/TO/x-mcp 替换为你克隆仓库的实际路径，然后重启 Claude Code。

Claude Desktop

将以下内容添加到你的 claude_desktop_config.json 文件中：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "x-twitter": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/x-mcp/dist/index.js"],
      "env": {
        "X_API_KEY": "your_consumer_key",
        "X_API_SECRET": "your_secret_key",
        "X_ACCESS_TOKEN": "your_access_token",
        "X_ACCESS_TOKEN_SECRET": "your_access_token_secret",
        "X_BEARER_TOKEN": "your_bearer_token"
      }
    }
  }
}

Cursor

将以下内容添加到你的 Cursor MCP 配置文件中：

• 全局（所有项目）：~/.cursor/mcp.json
• 项目范围：项目根目录下的 .cursor/mcp.json

{
  "mcpServers": {
    "x-twitter": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/x-mcp/dist/index.js"],
      "env": {
        "X_API_KEY": "your_consumer_key",
        "X_API_SECRET": "your_secret_key",
        "X_ACCESS_TOKEN": "your_access_token",
        "X_ACCESS_TOKEN_SECRET": "your_access_token_secret",
        "X_BEARER_TOKEN": "your_bearer_token"
      }
    }
  }
}

你还可以在 Cursor 设置 > MCP 服务器中验证连接。

OpenAI Codex

选项 A：命令行界面（CLI）

codex mcp add x-twitter --env X_API_KEY=your_consumer_key --env X_API_SECRET=your_secret_key --env X_ACCESS_TOKEN=your_access_token --env X_ACCESS_TOKEN_SECRET=your_access_token_secret --env X_BEARER_TOKEN=your_bearer_token -- node /ABSOLUTE/PATH/TO/x-mcp/dist/index.js

选项 B：config.toml

将以下内容添加到 ~/.codex/config.toml（全局）或 .codex/config.toml（项目范围）中：

[mcp_servers.x-twitter]
command = "node"
args = ["/ABSOLUTE/PATH/TO/x-mcp/dist/index.js"]

[mcp_servers.x-twitter.env]
X_API_KEY = "your_consumer_key"
X_API_SECRET = "your_secret_key"
X_ACCESS_TOKEN = "your_access_token"
X_ACCESS_TOKEN_SECRET = "your_access_token_secret"
X_BEARER_TOKEN = "your_bearer_token"

Windsurf

将以下内容添加到 ~/.codeium/windsurf/mcp_config.json 中：

{
  "mcpServers": {
    "x-twitter": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/x-mcp/dist/index.js"],
      "env": {
        "X_API_KEY": "your_consumer_key",
        "X_API_SECRET": "your_secret_key",
        "X_ACCESS_TOKEN": "your_access_token",
        "X_ACCESS_TOKEN_SECRET": "your_access_token_secret",
        "X_BEARER_TOKEN": "your_bearer_token"
      }
    }
  }
}

你也可以从 Windsurf 设置 > 级联 > MCP 服务器中添加。

Cline（VS Code）

打开 Cline 的 MCP 设置（点击 Cline 顶部导航栏中的 MCP 服务器图标 > 配置），然后将以下内容添加到 cline_mcp_settings.json 中：

{
  "mcpServers": {
    "x-twitter": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/x-mcp/dist/index.js"],
      "env": {
        "X_API_KEY": "your_consumer_key",
        "X_API_SECRET": "your_secret_key",
        "X_ACCESS_TOKEN": "your_access_token",
        "X_ACCESS_TOKEN_SECRET": "your_access_token_secret",
        "X_BEARER_TOKEN": "your_bearer_token"
      },
      "alwaysAllow": [],
      "disabled": false
    }
  }
}

其他 MCP 客户端

这是一个标准的标准输入输出 MCP 服务器。对于任何兼容 MCP 的客户端，请将其指向：

node /ABSOLUTE/PATH/TO/x-mcp/dist/index.js

并设置以下环境变量：X_API_KEY、X_API_SECRET、X_ACCESS_TOKEN、X_ACCESS_TOKEN_SECRET、X_BEARER_TOKEN。

📚 详细文档

故障排除

发布时出现 403 "oauth1-permissions" 错误

你的访问令牌是在启用写入权限之前生成的。请访问 X 开发者门户，确保应用权限设置为 "读取和写入"，然后 重新生成 你的访问令牌和密钥。

401 未授权错误

仔细检查 .env 文件中的所有 5 个凭证是否正确，确保没有额外的空格或换行符。

429 速率限制错误

错误消息会明确显示速率限制何时重置。请等待到该时间，或减少请求频率。

回复时出现权限/限制错误

截至 2024 年 2 月，X 通过 API 限制程序化回复。只有当原作者 @提及你或引用你的推文时，你才能进行回复。这适用于免费、基础、专业和按使用付费层级（企业层级除外）。你可以使用 quote_tweet 作为替代方法。

服务器显示 "已连接" 但工具未使用

确保你以正确的范围（用户/全局，如果你希望在所有地方都可用，则不要使用项目范围）添加了服务器，然后重启客户端。

速率限制

每个响应都包含速率限制信息：剩余请求数、总限制和重置时间。当达到限制时，你将收到一个明确的错误消息，其中包含确切的重置时间戳。

分页

列表端点在响应中返回 next_token。你可以传递该令牌以获取下一页结果。此功能适用于 search_tweets、get_timeline、get_mentions、get_followers、get_following。

搜索查询语法

search_tweets 工具支持 X 的完整查询语言：

• from:username -- 特定用户发布的推文
• to:username -- 对特定用户的回复
• #hashtag -- 包含特定话题标签的推文
• "exact phrase" -- 精确文本匹配
• has:media / has:links / has:images -- 按内容类型过滤
• is:reply / -is:retweet -- 按推文类型过滤
• lang:en -- 按语言过滤
• 可以使用空格（AND）或 OR 进行组合

📄 许可证

本项目采用 MIT 许可证。