X (Twitter) MCP server

X（Twitter）MCP 服务器

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

特征

• 获取用户个人资料、关注者和关注列表。
• 发布、删除和收藏推文。
• 在 Twitter 上搜索推文和趋势。
• 管理书签和时间线。
• Twitter API 的内置速率限制处理。
• 使用具有适当身份验证（API 密钥和令牌）的 Twitter API v2，避免用户名/密码被黑客入侵，从而最大限度地降低帐户被暂停的风险。
• 为用户管理、推文管理、时间线和搜索功能提供 Twitter API v2 端点的完整实现。

先决条件

• Python 3.10 或更高版本：确保您的系统上安装了 Python。
• Twitter 开发者帐户：您需要来自Twitter 开发者门户的 API 凭证（API 密钥、API 机密、访问令牌、访问令牌机密和承载令牌）。
• 可选： Claude Desktop ：从Anthropic 网站下载并安装 Claude Desktop 应用程序。
• 可选： Node.js （用于 MCP 集成）：在 Claude Desktop 中运行 MCP 服务器所必需的。
• 用于 Python 依赖项的包管理器（如uv或pip 。

安装

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

通过Smithery自动为 Claude Desktop 安装 X（Twitter）MCP 服务器：

选项 2：从 PyPI 安装

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

选项 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

运行服务器

您可以通过两种方式运行服务器：

选项 1：使用 CLI 脚本

该项目定义了一个 CLI 脚本x-twitter-mcp-server 。

如果从 PyPI 安装：

如果使用uv从源安装：

选项 2：直接使用 FastMCP（仅限源代码）

如果您从源代码安装并且更喜欢使用 FastMCP 的开发模式运行服务器：

服务器将启动并监听 MCP 连接。您应该看到如下输出：

与 Claude Desktop 一起使用

要将此 MCP 服务器与 Claude Desktop 配合使用，您需要配置 Claude 以连接到服务器。请按照以下步骤操作：

步骤1：安装Node.js

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

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

第 2 步：找到 Claude 桌面配置

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替换为你的项目目录的实际路径（如果是从源码安装的）或 Python 可执行文件的路径（如果是从 PyPI 安装的）。

如果从 PyPI 安装：

如果使用uv从源安装：

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

步骤4：重启Claude Desktop

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

步骤5：验证连接

• 打开 Claude 桌面。
• 在输入区域（右下角）找到锤子或连接器图标。这表示 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 工具进行聊天会话的权限。

可用工具

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

用户管理工具

get_user_profile

• 描述：获取用户的详细个人资料信息。
• Claude 桌面示例：
  Get the Twitter profile for user ID 123456789.
  Claude 将返回用户的个人资料详细信息，包括 ID、姓名、用户名、个人资料图片 URL 和描述。

get_user_by_screen_name

• 描述：通过屏幕名称获取用户。
• Claude 桌面示例：
  Get the Twitter user with screen name "example_user".
  Claude 将返回用户的个人资料详细信息。

get_user_by_id

• 描述：通过 ID 获取用户。
• Claude 桌面示例：
  Fetch the Twitter user with ID 987654321.
  Claude 将返回用户的个人资料详细信息。

get_user_followers

• 描述：检索给定用户的关注者列表。
• Claude 桌面示例：
  Get the followers of user ID 123456789, limit to 50.
  克劳德将返回最多 50 名关注者的列表。

get_user_following

• 描述：检索给定用户正在关注的用户。
• Claude 桌面示例：
  Who is user ID 123456789 following? Limit to 50 users.
  Claude 将返回最多 50 个用户的列表。

get_user_followers_you_know

• 描述：检索常见关注者列表。
• Claude 桌面示例：
  Get common followers for user ID 123456789, limit to 50.
  Claude 将返回最多 50 个共同关注者的列表（通过过滤关注者来模拟）。

get_user_subscriptions

• 描述：检索指定用户订阅的用户列表。
• Claude 桌面示例：
  Get the subscriptions for user ID 123456789, limit to 50.
  Claude 将返回最多 50 个用户的列表（使用以下作为订阅的代理）。

推文管理工具

post_tweet

• 描述：发布带有可选媒体、回复和标签的推文。
• Claude 桌面示例：
  Post a tweet saying "Hello from Claude Desktop! #MCP"
  克劳德将发布推文并返回推文详情。

delete_tweet

• 描述：通过 ID 删除推文。
• Claude 桌面示例：
  Delete the tweet with ID 123456789012345678.
  克劳德将删除该推文并确认该操作。

get_tweet_details

• 描述：获取有关特定推文的详细信息。
• Claude 桌面示例：
  Get details for tweet ID 123456789012345678.
  Claude 将返回推文的详细信息，包括 ID、文本、创建日期和作者 ID。

create_poll_tweet

• 描述：创建带有投票的推文。
• Claude 桌面示例：
  Create a poll tweet with the question "What's your favorite color?" and options "Red", "Blue", "Green" for 60 minutes.
  克劳德将创建民意调查推文并返回推文详情。

vote_on_poll

• 描述：进行民意调查。
• Claude 桌面示例：
  Vote "Blue" on the poll in tweet ID 123456789012345678.
  Claude 将返回一个模拟响应（因为 Twitter API v2 不支持投票）。

favorite_tweet

• 描述：收藏一条推文。
• Claude 桌面示例：
  Like the tweet with ID 123456789012345678.
  克劳德将收藏该推文并确认该操作。

unfavorite_tweet

• 描述：取消收藏推文。
• Claude 桌面示例：
  Unlike the tweet with ID 123456789012345678.
  克劳德将取消收藏该推文并确认该操作。

bookmark_tweet

• 描述：将推文添加到书签。
• Claude 桌面示例：
  Bookmark the tweet with ID 123456789012345678.
  克劳德将收藏该推文并确认该操作。

delete_bookmark

• 描述：从书签中删除推文。
• Claude 桌面示例：
  Remove the bookmark for tweet ID 123456789012345678.
  克劳德将删除书签并确认该操作。

delete_all_bookmarks

• 描述：删除所有书签。
• Claude 桌面示例：
  Delete all my Twitter bookmarks.
  克劳德将删除所有书签并确认该操作。

时间线和搜索工具

get_timeline

• 描述：从您的主页时间线获取推文（为您）。
• Claude 桌面示例：
  Show my Twitter For You timeline, limit to 20 tweets.
  克劳德将从您的 For You 时间线返回最多 20 条推文。

get_latest_timeline

• 描述：从您的主页时间线获取推文（关注）。
• Claude 桌面示例：
  Show my Twitter Following timeline, limit to 20 tweets.
  克劳德将从您的关注时间线返回最多 20 条推文。

search_twitter

• 描述：通过查询搜索 Twitter。
• Claude 桌面示例：
  Search Twitter for recent tweets about AI, limit to 10.
  克劳德将回复最多 10 条有关 AI 的最新推文。

get_trends

• 描述：检索 Twitter 上的热门话题。
• Claude 桌面示例：
  What are the current trending topics on Twitter? Limit to 10.
  克劳德将返回最多 10 个热门话题。

get_highlights_tweets

• 描述：从用户的时间线中检索突出显示的推文。
• Claude 桌面示例：
  Get highlighted tweets from user ID 123456789, limit to 20.
  Claude 将从用户的时间线返回最多 20 条推文（模拟为精彩片段）。

get_user_mentions

• 描述：获取提及特定用户的推文。
• Claude 桌面示例：
  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_desktop_config.json中的路径正确。
  • 确保command和args指向正确的可执行文件和脚本。
  • 更新配置文件后重新启动 Claude Desktop。
  • 检查 Claude 的开发者模式日志（帮助 → 启用开发者模式 → 打开 MCP 日志文件）是否有错误。
• 速率限制错误：
  • 该服务器包括速率限制处理，但如果您达到 Twitter API 限制，则可能需要等待重置窗口（例如，推文操作需要 15 分钟）。
• 语法警告：
  • 如果您在 Tweepy 中看到SyntaxWarning消息，则是由于 Python 3.13 版本的 Tweepy 中的文档字符串问题造成的。服务器包含一个警告抑制功能来处理此问题。

贡献

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

执照

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

作者

• Rafal Janicki - rafal@kult.io