X (Twitter) MCP 服务

本项目是基于 twikit 实现的 Model Context Protocol (MCP) 服务，专门为 AI 助手、大语言模型及各类 AI Agent 提供与 X (Twitter) 交互的能力。通过本服务，AI 能够自主调用工具完成状态感知、发推（含图片）、读写评论、收发私信、关注互动、趋势发现以及重点账号追踪等全流程操作。

服务通过普通账号的浏览器 Cookie（auth_token 与 ct0）与 X 官方 Web 端通信。所有工具统一采用结构化 JSON 响应，确保状态判定与字段解析的稳定性。

功能列表

服务目前为 AI 助手提供以下 29 个 MCP 工具，按模块划分如下：

1. 推文发布与社交互动

2. 推文与评论检索

3. 用户资料与社交关系

4. 状态感知与趋势发现

5. 私信交流与推文分享

6. 特定关注账号追踪 (VIP Watchlist)

统一响应数据结构

所有工具的返回值均采用规范的 JSON 文本格式输出，便于大语言模型进行条件判断与进一步工具链编排：

{
  "status": "success",
  "tool": "get_notifications",
  "message": "最新通知感知概览 (共 6 条)：点赞 3 条 | 新粉丝 1 人 | 回复 2 条",
  "data": {
    "total": 6,
    "summary": { "likes": 3, "follows": 1, "replies": 2 },
    "notifications": [
      {
        "id": "HVdLtUjaAAAAAAABSQ3bEYMUcp7plCkwmRQ",
        "type": "like",
        "message": "UserA liked your post",
        "from_user": { "screen_name": "UserA", "name": "Alice", "id": "123456" },
        "tweet": { "id": "2115110580302557481", "text": "Hello world" },
        "timestamp_ms": "1730100000000"
      }
    ]
  }
}

若操作遇到错误、网络超时或触发限额，返回格式严格标明失败状态，避免误报成功：

{
  "status": "failed",
  "tool": "follow_user",
  "message": "关注用户失败: User @invalid_name not found.",
  "error": "User not found"
}

安装与部署

1. 克隆仓库与安装依赖

环境要求：Python 3.10 及以上。

git clone https://github.com/yxiy171866-boop/x-twikit-mcp.git
cd x-twikit-mcp
pip install -r requirements.txt

2. 获取与配置 Cookie

运行服务需要两个 Cookie 字段：auth_token 与 ct0。

1. 在电脑浏览器中打开并登录 x.com。
2. 按 F12 打开浏览器开发者工具。
3. 进入 Application（Chrome/Edge）或 存储 (Storage)（Firefox）标签页。
4. 展开左侧的 Cookies，选择 https://x.com。
5. 在列表中找到并复制以下两项的值：
   • auth_token
   • ct0

配置方式（二选一）

• 方式一：通过环境变量配置（推荐）

  export TWITTER_AUTH_TOKEN="你的 auth_token"
  export TWITTER_CT0="你的 ct0"
  

• 方式二：通过配置文件配置
  复制根目录下的 cookies.json.example 为 cookies.json：

  {
    "auth_token": "你的 auth_token",
    "ct0": "你的 ct0"
  }
  

  服务会优先读取环境变量，未设置时读取当前目录下的 cookies.json。

客户端配置示例

Claude Desktop

在 Claude Desktop 配置文件中添加服务配置：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "twitter": {
      "command": "python3",
      "args": ["/绝对路径/x-twikit-mcp/server.py"],
      "env": {
        "TWITTER_AUTH_TOKEN": "你的 auth_token",
        "TWITTER_CT0": "你的 ct0"
      }
    }
  }
}

Cursor

在项目目录的 .cursor/mcp.json 或全局 Cursor 设置中添加：

{
  "mcpServers": {
    "twitter": {
      "command": "python3",
      "args": ["/绝对路径/x-twikit-mcp/server.py"],
      "env": {
        "TWITTER_AUTH_TOKEN": "你的 auth_token",
        "TWITTER_CT0": "你的 ct0"
      }
    }
  }
}

通用第三方客户端与 Agent 平台（如 Cherry Studio、Chatbox 等）

方式一：一键粘贴 JSON

在客户端的 JSON 配置框中粘贴以下内容：

{
  "command": "python3",
  "args": ["/绝对路径/x-twikit-mcp/server.py"],
  "env": {
    "TWITTER_AUTH_TOKEN": "你的 auth_token",
    "TWITTER_CT0": "你的 ct0"
  }
}

方式二：表单填写

• 服务名称 / 标识符：twitter（或自定义名称）
• 传输协议 (Transport)：stdio
• 启动命令 (Command)：python3
• 启动参数 (Arguments)：/绝对路径/x-twikit-mcp/server.py
• 环境变量 (Environment)：

  {
    "TWITTER_AUTH_TOKEN": "你的 auth_token",
    "TWITTER_CT0": "你的 ct0"
  }
  

常见问题与使用限制

1. 网络与代理设置

若处于无法直连 X (Twitter) 的网络环境中，客户端调用可能出现 ConnectTimeout 或 ConnectError。
可以在客户端配置的环境变量（env）中补充代理地址：

"env": {
  "TWITTER_AUTH_TOKEN": "你的 auth_token",
  "TWITTER_CT0": "你的 ct0",
  "HTTP_PROXY": "http://127.0.0.1:7890",
  "HTTPS_PROXY": "http://127.0.0.1:7890"
}

2. 官方风控与错误码排查

当调用频率过高或触发平台规则时，接口可能返回以下错误码：

3. 业务场景与环境限制

• 私信权限限制：若目标用户关闭了陌生人私信接收权限（例如设置为仅允许互关好友或认证用户私信），发送私信会调用失败。
• 依赖库更新：底层依赖的 twikit 库基于网页端 GraphQL 接口实现。若平台调整接口结构，可运行 pip install -U twikit 更新底层库。
• 本地环境与路径：若系统中安装了多个 Python 版本，导致提示 ModuleNotFoundError: No module named 'twikit'，请将配置文件中的 "command": "python3" 替换为安装了对应依赖的 Python 解释器绝对路径。

更新日志

详情可参考 CHANGELOG.md。

• v1.2.0 (2026-10-29): 新增通知感知、热门趋势、重点关注账号名单（VIP Watchlist）、关注/取关、粉丝/关注列表读取、书签管理、引用推文、私信分享推文、图片多媒体发推、高级搜索过滤条件，统一 29 个工具的结构化 JSON 返回规范。
• v1.1.0 (2026-10-28): 增加单条推文全指标详情查询（含收藏与浏览量）、用户主页资料与用户推文精准抓取，优化 GraphQL 回复线程解析。
• v1.0.0 (2026-10-28): 首个公开版本发布，提供发推、回复、读评、私信与基础搜索能力。

开源协议

本项目采用 MIT License 授权。