X (Twitter) MCP server

X (Twitter) MCP 服务

一个用于通过 AI 工具与 Twitter (X) 交互的模型上下文协议（MCP）服务。通过 AI 工具中的自然语言命令，此服务可让你获取推文、发布推文、搜索 Twitter、管理关注者等。

功能

• 获取用户资料、关注者和关注列表。
• 发布、删除和收藏推文。
• 搜索 Twitter 推文和趋势。
• 管理书签和时间线。
• 内置 Twitter API 速率限制处理。
• 使用带有适当身份验证（API 密钥和令牌）的 Twitter API v2，避免使用用户名/密码的变通方法，以降低账号被封禁的风险。
• 提供 Twitter API v2 端点的完整实现，支持用户管理、推文管理、时间线和搜索功能。

先决条件

• Python 3.10 或更高版本：确保系统已安装 Python。
• Twitter Developer 账号：你需要从 Twitter Developer Portal 获取 API 凭据（API Key、API Secret、Access Token、Access Token Secret 和 Bearer Token）。
• 可选：Claude Desktop：从 Anthropic 网站下载并安装 Claude Desktop 应用。
• 可选：Node.js（用于 MCP 集成）：在 Claude Desktop 中运行 MCP 服务所需。
• 用于安装 Python 依赖项的包管理器，例如 uv 或 pip。

安装

选项 1：通过 Smithery 安装（推荐）

要通过 Smithery 自动为 Claude Desktop 安装 X (Twitter) MCP 服务：

npx -y @smithery/cli install @rafaljanicki/x-twitter-mcp-server --client claude

选项 2：从 PyPI 安装

安装 x-twitter-mcp 最简单的方法是通过 PyPI：

pip install x-twitter-mcp

选项 3：从源代码安装

如果你希望从源代码仓库安装：

1. 克隆仓库：

   git clone https://github.com/rafaljanicki/x-twitter-mcp-server.git
   cd x-twitter-mcp-server
   

2. 设置虚拟环境（可选，但建议执行）：

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

3. 安装依赖项： 使用 uv（推荐，因为项目使用 uv.lock）：

   uv sync
   

   或者，使用 pip：

   pip install .
   

4. 配置环境变量：

   • 在项目根目录创建 .env 文件（如果提供了 .env.example，可以复制该文件）。
   • 添加你的 Twitter API 凭据：

     TWITTER_API_KEY=your_api_key
     TWITTER_API_SECRET=your_api_secret
     TWITTER_ACCESS_TOKEN=your_access_token
     TWITTER_ACCESS_TOKEN_SECRET=your_access_token_secret
     TWITTER_BEARER_TOKEN=your_bearer_token
     

   • 要使用书签工具（get_bookmarks、delete_all_bookmarks），还需添加 OAuth 2.0 用户访问令牌：

     TWITTER_OAUTH2_USER_ACCESS_TOKEN=your_oauth2_user_token
     

     请参阅下文的获取 OAuth 2.0 用户令牌。

获取 OAuth 2.0 用户令牌

书签端点（GET /2/users/:id/bookmarks、DELETE /2/users/:id/bookmarks/:tweet_id）需要 OAuth 2.0 用户上下文——它们不接受仅限应用的 bearer token 和 OAuth 1.0a。你需要执行一次 PKCE 授权流程来获取用户范围的令牌。

步骤

1. 在 Twitter Developer Portal 中，打开你的应用 → Settings → User authentication settings，然后启用 OAuth 2.0。设置回调 URL（例如 https://localhost/）。

2. 使用 Tweepy 运行 PKCE 流程：

import tweepy

handler = tweepy.OAuth2UserHandler(
    client_id="YOUR_CLIENT_ID",       # OAuth 2.0 Client ID (from Developer Portal)
    redirect_uri="https://localhost/",
    scope=["bookmark.read", "bookmark.write", "users.read", "offline.access"],
    client_secret="YOUR_CLIENT_SECRET",  # Optional for public clients
)

print(handler.get_authorization_url())
# Open the URL, authorize, copy the redirected URL, then:
redirected_url = input("Paste redirected URL: ")
token = handler.fetch_token(redirected_url)
print(token["access_token"])

3. 将生成的令牌设置为环境变量或 .env 文件中的 TWITTER_OAUTH2_USER_ACCESS_TOKEN。

运行服务

首选传输方式为 Streamable HTTP。使用以下任一方式：

推荐：Streamable HTTP（Docker/Smithery）

将服务作为 HTTP 服务运行，并提供 Streamable HTTP 和 SSE 端点。

1. 构建 Docker 镜像：

   docker build -t x-twitter-mcp .
   

2. 运行容器（Smithery 使用 PORT；此处默认值为 8081）：

   docker run -p 8081:8081 -e PORT=8081 x-twitter-mcp
   

3. 端点：

   • Streamable HTTP（基于 HTTP 的 JSON-RPC）：POST http://localhost:8081/mcp
   • SSE（服务器发送事件）：GET http://localhost:8081/sse

4. 通过 base64 编码的 config 查询参数按请求传递配置（推荐在 Smithery 中使用）。配置 JSON 示例：

   {"twitterApiKey":"...","twitterApiSecret":"...","twitterAccessToken":"...","twitterAccessTokenSecret":"...","twitterBearerToken":"..."}
   

   编码并调用 initialize：

   CONFIG_B64=$(printf '%s' '{"twitterApiKey":"YOUR_KEY","twitterApiSecret":"YOUR_SECRET","twitterAccessToken":"YOUR_TOKEN","twitterAccessTokenSecret":"YOUR_TOKEN_SECRET","twitterBearerToken":"YOUR_BEARER"}' | base64)
   
   curl -sS -X POST "http://localhost:8081/mcp?config=${CONFIG_B64}" \
     -H 'content-type: application/json' \
     -d '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"capabilities":{}}}'
   

注意：

• POST / 会返回 404；Streamable HTTP 请使用 /mcp，SSE 请使用 /sse。
• 通过 Smithery 部署时，smithery.yaml 已配置为 runtime: container 和 startCommand.type: http。

Streamable HTTP（本地，无 Docker）

直接运行 ASGI 服务。

如果从 PyPI 安装：

python -m x_twitter_mcp.http_server

如果使用 uv 从源代码安装：

uv run python -m x_twitter_mcp.http_server

端点和配置传递方式与上文相同。

旧版 STDIO（CLI 脚本）

本项目还提供 STDIO CLI 脚本 x-twitter-mcp-server，供需要 STDIO 的桌面客户端使用。

如果从 PyPI 安装：

x-twitter-mcp-server

如果使用 uv 从源代码安装：

uv run x-twitter-mcp-server

与 Claude Desktop 搭配使用

要在 Claude Desktop 中使用此 MCP 服务，需要配置 Claude 以连接到该服务。请按以下步骤操作：

步骤 1：安装 Node.js

Claude Desktop 使用 Node.js 运行 MCP 服务。如果尚未安装 Node.js：

• 从 nodejs.org 下载并安装 Node.js。
• 验证安装：

  node --version
  

步骤 2：找到 Claude Desktop 配置文件

Claude Desktop 使用 claude_desktop_config.json 文件配置 MCP 服务。

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

如果文件不存在，请创建该文件。

步骤 3：配置 MCP 服务

编辑 claude_desktop_config.json，添加 x-twitter-mcp 服务。如果从源代码安装，请将 /path/to/x-twitter-mcp-server 替换为项目目录的实际路径；如果从 PyPI 安装，请替换为 Python 可执行文件的路径。

如果从 PyPI 安装：

{
  "mcpServers": {
    "x-twitter-mcp": {
      "command": "x-twitter-mcp-server",
      "args": [],
      "env": {
        "PYTHONUNBUFFERED": "1",
        "TWITTER_API_KEY": "your_api_key",
        "TWITTER_API_SECRET": "your_api_secret",
        "TWITTER_ACCESS_TOKEN": "your_access_token",
        "TWITTER_ACCESS_TOKEN_SECRET": "your_access_token_secret",
        "TWITTER_BEARER_TOKEN": "your_bearer_token",
        "TWITTER_OAUTH2_USER_ACCESS_TOKEN": "your_oauth2_user_token"
      }
    }
  }
}

如果使用 uv 从源代码安装：

{
  "mcpServers": {
    "x-twitter-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/x-twitter-mcp-server",
        "run",
        "x-twitter-mcp-server"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

• "command": "x-twitter-mcp-server"：如果从 PyPI 安装，可直接使用 CLI 脚本。
• "env"：如果从 PyPI 安装，可能需要在配置中直接提供环境变量（因为没有 .env 文件）。如果从源代码安装，则会使用 .env 文件。
• "env": {"PYTHONUNBUFFERED": "1"}：确保输出不经过缓冲，以便在 Claude 中获得更好的日志记录。

步骤 4：重启 Claude Desktop

• 完全退出 Claude Desktop。
• 重新打开 Claude Desktop，以加载新配置。

步骤 5：验证连接

• 打开 Claude Desktop。
• 在输入区域（右下角）查找锤子或连接器图标。这表示 MCP 工具已可用。
• 点击该图标即可查看 x-twitter-mcp 提供的可用工具，例如 post_tweet、search_twitter、get_user_profile 等。

步骤 6：使用 Claude 进行测试

现在，你可以在 Claude Desktop 中使用自然语言与 Twitter 交互。以下是一些提示词示例：

• 获取用户资料：

  Get the Twitter profile for user ID 123456.
  

  Claude 将调用 get_user_profile 工具并返回用户的详细信息。

• 发布推文：

  Post a tweet saying "Hello from Claude Desktop! #MCP"
  

  Claude 将使用 post_tweet 工具发布推文并确认操作。

• 搜索 Twitter：

  Search Twitter for recent tweets about AI.
  

  Claude 将调用 search_twitter 工具并返回相关推文。

• 获取趋势：

  What are the current trending topics on Twitter?
  

  Claude 将使用 get_trends 工具获取热门话题。

收到提示时，请授权 Claude 在本次聊天会话中使用 MCP 工具。

OpenClaw 配套工作流

当 MCP 客户端需要直接调用 Twitter API v2 工具时，这个 MCP 服务最为适用。如果工作流运行在 OpenClaw 中，并需要插件安装元数据、端点发现、监控提醒、webhook、抽奖、媒体上传或下载工作流、私信、关注者导出，或需经审批的发帖和回复操作，请使用独立的 OpenClaw 插件 TweetClaw，并在工具之间传递已审核的推文 ID 或 URL。

请参阅 OpenClaw 配套工作流，了解如何在分离凭据的同时避免重复执行写入操作的命令流程。

可用工具

以下是 x-twitter-mcp 服务提供的所有工具，以及在 Claude Desktop 中使用自然语言提示词调用工具的示例。

用户管理工具

get_user_profile

• 描述：获取用户的详细资料信息。
• Claude Desktop 示例：

  Get the Twitter profile for user ID 123456789.
  

  Claude 将返回用户的资料详情，包括 ID、姓名、用户名、头像 URL 和简介。

get_user_by_screen_name

• 描述：通过屏幕名称获取用户。
• Claude Desktop 示例：

  Get the Twitter user with screen name "example_user".
  

  Claude 将返回用户的资料详情。

get_user_by_id

• 描述：通过 ID 获取用户。
• Claude Desktop 示例：

  Fetch the Twitter user with ID 987654321.
  

  Claude 将返回用户的资料详情。

get_user_followers

• 描述：获取指定用户的关注者列表。
• Claude Desktop 示例：

  Get the followers of user ID 123456789, limit to 50.
  

  Claude 将返回最多 50 位关注者的列表。

get_user_following

• 描述：获取指定用户关注的用户。
• Claude Desktop 示例：

  Who is user ID 123456789 following? Limit to 50 users.
  

  Claude 将返回最多 50 位用户的列表。

get_user_followers_you_know

• 描述：获取共同关注者列表。
• Claude Desktop 示例：

  Get common followers for user ID 123456789, limit to 50.
  

  Claude 将返回最多 50 位共同关注者（通过筛选关注者模拟）。

get_user_subscriptions

• 描述：获取指定用户订阅的用户列表。
• Claude Desktop 示例：

  Get the subscriptions for user ID 123456789, limit to 50.
  

  Claude 将返回最多 50 位用户的列表（以关注关系代替订阅关系）。

推文管理工具

post_tweet

• 描述：发布推文，可选择附带媒体、回复和标签。
• Claude Desktop 示例：

  Post a tweet saying "Hello from Claude Desktop! #MCP"
  

  Claude 将发布推文并返回推文详情。

delete_tweet

• 描述：通过推文 ID 删除推文。
• Claude Desktop 示例：

  Delete the tweet with ID 123456789012345678.
  

  Claude 将删除推文并确认操作。

get_tweet_details

• 描述：获取指定推文的详细信息。
• Claude Desktop 示例：

  Get details for tweet ID 123456789012345678.
  

  Claude 将返回推文详情，包括 ID、文本、创建日期和作者 ID。

create_poll_tweet

• 描述：创建带投票的推文。
• Claude Desktop 示例：

  Create a poll tweet with the question "What's your favorite color?" and options "Red", "Blue", "Green" for 60 minutes.
  

  Claude 将创建投票推文并返回推文详情。

vote_on_poll

• 描述：参与投票。
• Claude Desktop 示例：

  Vote "Blue" on the poll in tweet ID 123456789012345678.
  

  Claude 将返回模拟响应（因为 Twitter API v2 不支持投票）。

favorite_tweet

• 描述：喜欢推文。
• Claude Desktop 示例：

  Like the tweet with ID 123456789012345678.
  

  Claude 将喜欢该推文并确认操作。

unfavorite_tweet

• 描述：取消喜欢推文。
• Claude Desktop 示例：

  Unlike the tweet with ID 123456789012345678.
  

  Claude 将取消喜欢该推文并确认操作。

bookmark_tweet

• 描述：将推文加入书签。
• Claude Desktop 示例：

  Bookmark the tweet with ID 123456789012345678.
  

  Claude 将为该推文添加书签并确认操作。

delete_bookmark

• 描述：将推文从书签中移除。
• Claude Desktop 示例：

  Remove the bookmark for tweet ID 123456789012345678.
  

  Claude 将移除该书签并确认操作。

delete_all_bookmarks

• Description：具有破坏性且不可逆。通过获取每一页的内容并逐条删除，永久删除所有书签。需要 TWITTER_OAUTH2_USER_ACCESS_TOKEN。
• Claude Desktop Example：

  Delete all my Twitter bookmarks.
  

  Claude 会先向用户确认，然后删除所有书签并报告数量。

get_bookmarks

• Description：获取经过身份验证的用户收藏的推文。每次调用最多返回 100 条推文；使用 cursor 参数进行分页。需要 TWITTER_OAUTH2_USER_ACCESS_TOKEN。
• Claude Desktop Example：

  Show my Twitter bookmarks, limit to 25.
  

  Claude 最多返回 25 条收藏的推文，包括 ID、文本、创建日期和作者 ID。

时间线与搜索工具

get_timeline

• Description：获取主页时间线（为你推荐）中的推文。
• Claude Desktop Example：

  Show my Twitter For You timeline, limit to 20 tweets.
  

  Claude 最多返回 20 条为你推荐时间线中的推文。

get_latest_timeline

• Description：获取主页时间线（正在关注）中的推文。
• Claude Desktop Example：

  Show my Twitter Following timeline, limit to 20 tweets.
  

  Claude 最多返回 20 条正在关注时间线中的推文。

search_twitter

• Description：使用查询词搜索 Twitter。
• Claude Desktop Example：

  Search Twitter for recent tweets about AI, limit to 10.
  

  Claude 最多返回 10 条与 AI 相关的近期推文。

get_trends

• Description：获取 Twitter 上的热门话题。
• Claude Desktop Example：

  What are the current trending topics on Twitter? Limit to 10.
  

  Claude 最多返回 10 个热门话题。

get_highlights_tweets

• Description：获取用户时间线中的精选推文。
• Claude Desktop Example：

  Get highlighted tweets from user ID 123456789, limit to 20.
  

  Claude 最多返回用户时间线中的 20 条推文（模拟为精选内容）。

get_user_mentions

• Description：获取提及特定用户的推文。
• Claude Desktop Example：

  Get tweets mentioning user ID 123456789, limit to 20.
  

  Claude 最多返回 20 条提及该用户的推文。

故障排除

• 服务无法启动：

  • 确保 .env 文件包含所有必需的 Twitter API 凭据（如果是从源代码安装）。
  • 如果是从 PyPI 安装，请确保已在 claude_desktop_config.json 或 shell 中设置环境变量。
  • 运行 x-twitter-mcp-server 时，检查终端输出中的错误。
  • 确认已正确安装并可访问 uv 或 Python 可执行文件。

• Claude 未检测到服务：

  • 确认 claude_desktop_config.json 中的路径正确。
  • 确保 command 和 args 指向正确的可执行文件和脚本。
  • 更新配置文件后，重启 Claude Desktop。
  • 检查 Claude 的开发者模式日志（Help → Enable Developer Mode → Open MCP Log File）中的错误。

• 速率限制错误：

  • 服务包含速率限制处理机制，但如果达到 Twitter API 限制，可能需要等待限制重置（例如，推文操作需等待 15 分钟）。

• 书签工具返回 403：

  • get_bookmarks 和 delete_all_bookmarks 需要 TWITTER_OAUTH2_USER_ACCESS_TOKEN。书签端点不接受仅应用令牌和 OAuth 1.0a。
  • 查看获取 OAuth 2.0 用户令牌，了解设置说明。

• 语法警告：

  • 如果看到 Tweepy 发出的 SyntaxWarning 消息，这是 Tweepy 在 Python 3.13 中的文档字符串问题所致。服务包含警告抑制机制来处理此问题。

贡献

欢迎贡献！请在 GitHub 仓库中提交 issue 或 pull request。

许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。

作者

• Rafal Janicki - [email protected]