内容
<!-- mcp-name: io.github.jsilets/twscrape-twitter-mcp -->
# twscrape-twitter-mcp
[](https://pypi.org/project/twscrape-twitter-mcp/)
[](https://github.com/jsilets/twscrape-twitter-mcp/actions/workflows/ci.yml)
[](https://pypi.org/project/twscrape-twitter-mcp/)
[](LICENSE)
[](https://modelcontextprotocol.io)
一个读取X（Twitter）：帖子、线程、回复、引用和搜索的MCP服务器。它封装了[twscrape](https://github.com/vladkens/twscrape)，并使用您自己的登录会话，因此无需付费的X API，也无需开发者账户。工具返回干净的markdown格式，以便代理人阅读。
适用于任何MCP客户端，通过两种标准传输方式——本地**stdio**和托管**Streamable HTTP**。
## 工具
| 工具 | 返回 |
|---|---|
| `read_tweet(url_or_id)` | 一个帖子以markdown格式。 |
| `read_thread(url_or_id, max_replies=50)` | 根帖子 + 作者的自线程 + 顶级回复。 |
| `read_replies(url_or_id, limit=50)` | 帖子的回复。 |
| `read_quotes(url_or_id, limit=30)` | 引用推文（尽力而为，基于搜索）。 |
| `search(query, limit=20, product="Latest")` | 搜索结果。支持`from:`、`has:media`、`min_faves:`等。 |
## 安装
```bash
uv tool install twscrape-twitter-mcp # 或：pipx install twscrape-twitter-mcp
```
然后进行一次身份验证（下一节）并验证：
```bash
twscrape-twitter-mcp smoke # 读取一个公共推文端到端
```
## 身份验证
读取运行在您自己的X会话中。请选择一种路径：
**1. 启动专用浏览器（推荐）。** 打开一个单独的Chrome/Brave配置文件，带有DevTools端口，您一次性登录X，捕获会话。它不会触及您的日常浏览器或自动执行X的登录流程。
```bash
twscrape-twitter-mcp login --launch-browser chrome # 或：brave
```
**2. 附加到您已经打开的浏览器。** 使用调试端口启动您的浏览器，然后附加：
```bash
# macOS
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222
# Linux: google-chrome --remote-debugging-port=9222
# Windows: "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222
twscrape-twitter-mcp login --attach # 添加 --cdp-url 以获取非默认端口
```
**3. 无头/CI（原始cookie）。** 服务器无法打开您的桌面浏览器，因此使用`auth_token` + `ct0` cookie添加会话：
```bash
twscrape-twitter-mcp init --username YOU --auth-token AUTH --ct0 CT0
```
捕获的会话在重启期间重复使用。当它过期时再次运行`login`，或添加用于速率限制轮换的燃烧会话。`twscrape-twitter-mcp accounts`列出了池。
> 使用燃烧账户，而不是您的主要账户 - 参见[法律](#法律)。
## 连接您的客户端
服务器在stdio上本地运行。大多数MCP客户端采用以下JSON块：
```json
{
"mcpServers": {
"x": {
"command": "twscrape-twitter-mcp",
"args": ["serve", "--transport", "stdio"]
}
}
}
```
客户端特定等效项：
<details>
<summary><b>Claude 代码</b></summary>
```bash
claude mcp add x --scope user -- twscrape-twitter-mcp serve --transport stdio
```
</details>
<details>
<summary><b>Claude 桌面版</b></summary>
将上面的JSON块添加到`claude_desktop_config.json`（设置 → 开发者 → 编辑配置）。
</details>
<details>
<summary><b>Codex</b> — <code>~/.codex/config.toml</code></summary>
```toml
[mcp_servers.x]
command = "twscrape-twitter-mcp"
args = ["serve", "--transport", "stdio"]
```
</details>
<details>
<summary><b>Cursor</b> — <code>~/.cursor/mcp.json</code></summary>
```json
{
"mcpServers": {
"x": {
"command": "twscrape-twitter-mcp",
"args": ["serve", "--transport", "stdio"]
}
}
}
```
</details>
<details>
<summary><b>VS Code</b> — <code>.vscode/mcp.json</code></summary>
```json
{
"servers": {
"x": {
"command": "twscrape-twitter-mcp",
"args": ["serve", "--transport", "stdio"]
}
}
}
```
</details>
<details>
<summary><b>远程（Streamable HTTP）</b></summary>
对于托管实例（参见[部署](#部署)），请在客户端中指向HTTP端点，并带有Bearer令牌：
```json
{
"mcpServers": {
"x": {
"url": "https://YOUR-APP.example.com/mcp",
"headers": { "Authorization": "Bearer YOUR_TOKEN" }
}
}
}
```
</details>
然后询问，例如 *"读取此线程：<url>"*。
## 部署
始终运行服务器并通过HTTP（`POST /mcp`）可访问。它作为容器提供；Cloudflare Workers无法使用，因为twscrape是Python，具有本机依赖项。
无头容器无法打开您的桌面浏览器，因此请在本地进行身份验证（`login --attach`在`TWSCRAPE_TWITTER_MCP_HOME`下写入`storage_state.json`），然后将该会话发送到主机 - 将文件复制到挂载的卷中，或通过SSH运行基于cookie的`init`。服务器在启动时重新加载持久会话。
**在公开HTTP时始终设置令牌** - 任何可以访问端点的人都可以使用您的X会话：
```bash
export TWSCRAPE_TWITTER_MCP_AUTH_TOKEN=$(openssl rand -hex 32)
```
<details>
<summary><b>Fly.io</b></summary>
```bash
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
# 在卷上植入会话：
fly ssh console -C "twscrape-twitter-mcp init --username YOU --auth-token AUTH --ct0 CT0"
```
</details>
<details>
<summary><b>Railway</b></summary>
将Railway指向此仓库（它读取`railway.json` + `Dockerfile`），添加一个挂载在`/data`的卷，设置`TWSCRAPE_TWITTER_MCP_AUTH_TOKEN`，并通过Railway shell使用`twscrape-twitter-mcp init`植入会话。
</details>
客户端发送`Authorization: Bearer <token>`。
## 配置
| 环境变量 | 默认值 | 用途 |
|---|---|---|
| `TWSCRAPE_TWITTER_MCP_HOME` | `~/.config/twscrape-twitter-mcp` | sqlite账户池存储位置。在生产环境中指向一个卷。 |
| `TWSCRAPE_TWITTER_MCP_DB` | `$TWSCRAPE_TWITTER_MCP_HOME/accounts.db` | 直接覆盖池路径。 |
| `TWSCRAPE_TWITTER_MCP_AUTH_TOKEN` | _(未设置)_ | HTTP传输所需的Bearer令牌。 |
| `TWSCRAPE_TWITTER_MCP_PROXY` | _(未设置)_ | 每个账户的全局代理。 |
| `TWSCRAPE_TWITTER_MCP_CDP_URL` | `http://127.0.0.1:9222` | 用于`login --attach`的浏览器DevTools端点。 |
| `TWSCRAPE_TWITTER_MCP_DEFAULT_LIMIT` | `40` | 默认结果数。 |
| `PORT` | `8080` | HTTP端口（Railway注入此值）。 |
## 工作原理
读取X的最困难部分 - GraphQL签名、`x-client-transaction-id`头部、TLS指纹 - 完全位于`twscrape`中，该版本固定（`twscrape==0.19.0`）。此包是顶层的只读MCP层，绝不触及该机制。当X更改某些内容并且读取操作中断时，修复是版本升级，而不是逆向工程。
## 限制
- X可以过期、限制速率或暂停会话后面的帐户。
- 受保护、删除、地理阻止或以其他方式限制的帖子可能不可读。
- 引用推文的覆盖范围是基于搜索的不完整。
- 搜索结果取决于X当前的搜索行为，可能会因会话而异。
- 它不解密浏览器cookie存储 - 使用浏览器附件或cookie `init`。
## 法律
使用您自己的登录会话读取X可能违反X的使用条款，用于抓取的帐户可能会受到速率限制或暂停。使用燃烧帐户，而不是您的主要帐户。本工具按原样提供，用于研究和个人使用；您负责如何使用它。
## 许可证
MIT.
## 致谢
艰难的抓取工作由vladkens的[`twscrape`](https://github.com/vladkens/twscrape)完成。这是顶层的只读MCP层 - 请给它点赞。
