twscrape Twitter/X (read-only)

twscrape-twitter-mcp

一个用于读取 X（Twitter）内容的 MCP 服务：帖子、帖子串、回复、引用和搜索。它封装了 twscrape，并使用你自己的已登录会话，因此无需付费的 X API，也无需开发者账号。工具返回格式简洁、便于 Agent 阅读的 Markdown，其中包含图片、视频和 GIF 的 URL，以及帖子中的任何外部链接。

可通过两种标准传输方式与任何 MCP 客户端配合使用：本地 stdio 和托管的 Streamable HTTP。

工具

安装

uv tool install twscrape-twitter-mcp     # or: pipx install twscrape-twitter-mcp

然后完成一次身份验证（见下一节）并验证：

twscrape-twitter-mcp smoke               # reads one public tweet end-to-end

身份验证

读取操作使用你自己的 X 会话。选择一种方式：

1. 启动专用浏览器（推荐）。 打开一个带有 DevTools 端口的独立 Chrome/Brave 配置文件，你只需登录一次 X，即可捕获会话。此操作不会影响你日常使用的浏览器，也不会自动执行 X 的登录流程。

twscrape-twitter-mcp login --launch-browser chrome   # or: brave

2. 附加到专用浏览器配置文件。 仅当你已经运行带有调试端口的独立 Chromium 配置文件时使用。浏览器调试会暴露浏览器数据，而且近期版本的 Chrome 不会为默认配置文件启用此功能。

# macOS
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222 --user-data-dir=/tmp/x-mcp-browser
# Linux:   google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/x-mcp-browser
# Windows: "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir=%TEMP%\x-mcp-browser

twscrape-twitter-mcp login --attach                  # add --cdp-url for a non-default port

3. 无头模式 / CI（原始 Cookie）。 服务端无法打开你桌面上的浏览器，因此需使用 auth_token + ct0 Cookie 添加会话。运行时不要带 Cookie 标志，这样可以通过隐藏提示输入值，而不会将密钥留在 shell 历史记录中：

twscrape-twitter-mcp init

捕获的会话会在重启后继续使用。会话过期时，或要添加用于速率限制轮换的备用会话时，再次运行 login --launch-browser chrome。twscrape-twitter-mcp accounts 会列出会话池。

请使用备用账号，而非主账号 — 详见法律。

连接客户端

服务通过 stdio 在本地运行。大多数 MCP 客户端都接受类似这样的 JSON 块：

{
  "mcpServers": {
    "x": {
      "command": "twscrape-twitter-mcp",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}

各客户端的配置方式：

claude mcp add x --scope user -- twscrape-twitter-mcp serve --transport stdio

[mcp_servers.x]
command = "twscrape-twitter-mcp"
args = ["serve", "--transport", "stdio"]

{
  "mcpServers": {
    "x": {
      "command": "twscrape-twitter-mcp",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}

{
  "servers": {
    "x": {
      "command": "twscrape-twitter-mcp",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}

{
  "mcpServers": {
    "x": {
      "url": "https://YOUR-APP.example.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

然后可以询问，例如：“读取此帖子串：<url>”。

部署

始终运行服务，并确保可通过 HTTP 访问（POST /mcp）。它以容器形式提供；Cloudflare Workers 无法运行，因为 twscrape 是带有原生依赖项的 Python 程序。

无头容器无法打开你的桌面浏览器，因此请先在本地完成身份验证（login --attach 会在 TWSCRAPE_TWITTER_MCP_HOME 下写入 storage_state.json），然后将该会话传到主机上——把文件复制到挂载卷，或通过 SSH 运行基于 Cookie 的 init。服务会在启动时重新加载已持久化的会话。

通过 HTTP 暴露服务时，务必设置令牌——任何能够访问该端点的人都可以使用你的 X 会话：

export TWSCRAPE_TWITTER_MCP_AUTH_TOKEN=$(openssl rand -hex 32)

fly launch --no-deploy
fly volumes create twscrape_twitter_mcp_data --size 1
fly secrets set TWSCRAPE_TWITTER_MCP_AUTH_TOKEN=$(openssl rand -hex 32)
fly deploy
# seed a session onto the volume through hidden prompts:
fly ssh console -C "twscrape-twitter-mcp init"

客户端发送 Authorization: Bearer <token>。

配置

工作原理

读取 X 的难点——GraphQL 签名、x-client-transaction-id 标头和 TLS 指纹识别——完全由固定版本的 twscrape 处理。此软件包是在其之上的只读 MCP 层，不会触及这些机制。当 X 更改某些内容导致读取失效时，只需升级版本，无需逆向工程。

限制

• X 可能会使你会话对应的账号登录过期、限制其速率，或暂停该账号。
• 受保护、已删除、被地理位置屏蔽或受到其他限制的帖子可能无法读取。
• 引用推文的覆盖范围基于搜索，且并不完整。
• 搜索结果取决于 X 当前的搜索行为，并可能因会话而异。
• 它不会解密浏览器 Cookie 存储——请使用浏览器连接或 Cookie init。

法律声明

使用你自己的已登录会话读取 X 可能违反 X 的服务条款，用于抓取内容的账号也可能受到速率限制或被暂停。请使用备用账号，不要使用主账号。本软件按原样提供，仅供研究和个人使用；你需对自己的使用方式负责。

许可证

MIT。

致谢

抓取工作的核心由 vladkens 编写的 twscrape 完成。本项目是在其之上的只读 MCP 层——欢迎为它点星。