金大哥 - x-mcp MCP 详情

article

README

🚀 x-mcp

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

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

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

🚀 快速开始

🔍 功能概述

| 类别 | 工具 | 可使用的指令示例 | |------|------|------------------| | 发布 | post_tweet、reply_to_tweet、quote_tweet、delete_tweet | "在 X 上发布 'hello world'" / "回复这条推文并表示感谢" | | 读取 | get_tweet、search_tweets、get_timeline、get_mentions | "展示 @elonmusk 的最新推文" / "搜索关于 MCP 的推文" | | 用户 | get_user、get_followers、get_following | "查找 @openai" / "这个用户关注了谁？" | | 互动 | like_tweet、retweet | "点赞那条推文" / "转发这条推文" | | 媒体 | upload_media | "上传这张图片并配上说明文字..." | | 分析 | get_metrics | "我上一条推文获得了多少展示量？" |

该项目支持使用推文的 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) 创建应用

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

b) 启用写入权限

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

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

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

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

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

如果你在生成令牌之前跳过了步骤 (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 许可证。

x-mcp