内容
<!-- mcp-name: io.github.nsozturk/tweetkit-x -->
<p align="center">
<img src="assets/header.png" alt="tweetkit-x — 在 X (Twitter) 上发布、删除和阅读，使用 Python 和 MCP 服务器，基于您自己的网页会话" width="100%">
</p>
<h1 align="center">tweetkit-x</h1>
<p align="center">
<b>在 X (Twitter) 上发布、删除和阅读 — 使用 Python <i>和</i> MCP 服务器 — 基于您自己的已登录网页会话。</b><br>
无需付费 API。无需开发者应用。无需 OAuth 流程。只需您的会话 cookie。
</p>
<p align="center">
<img alt="PyPI" src="https://img.shields.io/pypi/v/tweetkit-x?style=flat-square&color=1d9bf0&label=pypi">
<img alt="Python" src="https://img.shields.io/badge/python-3.10+-1d9bf0?style=flat-square">
<img alt="License" src="https://img.shields.io/badge/license-MIT-3fb950?style=flat-square">
<img alt="MCP" src="https://img.shields.io/badge/MCP-server%20included-7856ff?style=flat-square">
<img alt="X API" src="https://img.shields.io/badge/X%20API-not%20required-3fb950?style=flat-square">
<img alt="Runs with" src="https://img.shields.io/badge/runs%20with-Claude%20%7C%20Cursor%20%7C%20uvx-111318?style=flat-square">
</p>
<p align="center">
<a href="#快速开始">快速开始</a> ·
<a href="#获取会话cookie">获取 cookie</a> ·
<a href="#python-用法">Python</a> ·
<a href="#命令行用法">命令行</a> ·
<a href="#mcp-服务器">MCP 服务器</a> ·
<a href="#工作原理">工作原理</a> ·
<a href="#免责声明">免责声明</a>
</p>
---
## 为什么
自 **2026 年 2 月 6 日** 起，X 的官方 API 已 **不再为新开发者提供免费层** — 采用按需付费模式：**每条帖子约 0.015 美元，每条带链接的帖子约 0.20 美元**，以及每条阅读记录的费用。对于发布您**自己的**推文（一个发布内容的机器人、一个预定的线程、一个删除旧帖子的清理脚本），这是一笔持续的账单，而您的浏览器已经可以免费完成这些操作。
**tweetkit-x** 完全跳过 API。它重现了您在浏览器中点击 **发布**、**删除** 或滚动浏览个人资料时，X 发出的确切内部 HTTP 调用 — 使用您已经拥有的会话 cookie 进行身份验证。发布、删除和阅读完整的timeline，**无需支付任何 API 费用**。
> ⚠️ 自动执行网页会话是 **违反 X 服务条款** 的。本工具是一个灰色地带工具，用于个人自动化。**账户风险完全由您承担**。请参阅 [免责声明](#免责声明)。
---
## 功能
- ✅ **发布** — 文本，**最多 4 张图片**，**GIF 和视频**（带有 **替代文本**），回复，**线程**，**引用推文**，**长格式笔记推文** 和 **预定** 推文
- 🗑️ **删除** — 单个 ID，一个 ID 列表，或 "查找并删除" 清理循环
- ❤️ **互动** — 点赞，转发，收藏，**关注，屏蔽，静音，置顶** — 每个都有撤销功能
- 🌐 **搜索整个 X** — 真实的 `SearchTimeline`（支持 `from:`，`min_faves:`，`filter:media` 等运算符），以及对您自己的推文的本地正则表达式搜索
- 📖 **阅读** — 您的 **首页**，任何时间线，推文的 **回复/对话**，**关注者/关注中**，**点赞者/转发者**，**收藏**，用户的 **点赞**，**通知** 和完整的 **个人资料**
- 🔌 **MCP 服务器** — **40 种工具**；可与 Claude Desktop / Claude Code / Cursor 结合使用；工具有 **解释 cookie** 并通过一次粘贴设置 cookie
- 🔑 **无缝身份验证** — 粘贴 `Cookie:` 头部，丢弃 **HAR** 文件，或 **存储转储 zip**；存储在文件中或 macOS **钥匙串** 中
- 🐍 **Python API** *和* **命令行**（`tweetkit …`）
- 🪶 小体积 — 无需无头浏览器，无需 Selenium
---
## 快速开始
```bash
pip install "tweetkit-x[mcp]" # 或：pip install tweetkit-x （仅限库和命令行）
# 1. 导入您的会话 cookie（三种方式 — 参见下一节）
tweetkit import --paste # 粘贴 Cookie: 头部，Ctrl-D
# 或： tweetkit import --file x.com.har
# 或： tweetkit import --file storagedump_x.com.zip --keychain tweetkit
# 2. 验证（无网络调用）
tweetkit whoami
# {"ready": true, "user_id": "1986...", "ct0_len": 160}
# 3. 使用它
tweetkit post "你好，世界 👋"
tweetkit search "xmr|monero" --regex # 您的匹配推文
tweetkit delete 2063240404980445603
```
---
## 获取会话 cookie
**tweetkit** 所需的唯一机密是您的 X **会话 cookie** — 与您已登录的浏览器发送的相同的 `Cookie:` 头部。它必须包含 **至少两个** 值：
| Cookie | 内容 | 是否必需 | HttpOnly? |
|---|---|---|---|
| `auth_token` | 您的登录/会话令牌 | **是** | **是** （在 `document.cookie` 中隐藏） |
| `ct0` | CSRF 令牌（作为 `x-csrf-token` 返回） | **是** | 否 |
| `twid` | 您的用户 ID（`u=<id>`）— 让 tweetkit 读取 *您的* 时间线，无需额外查找 | 推荐 | 否 |
| `guest_id`，`kdt`，`att`，`personalization_id` | 杂项会话状态 | 可选 | 混合 |
> ❗ `auth_token` 是 **HttpOnly**，因此在 JS 控制台中复制 `document.cookie` 将 **不** 包括它。使用以下可靠的方法之一。
### 方法 A — 复制 `Cookie:` 头部（最可靠，一次粘贴）
1. 在 **已登录** 的情况下打开 **x.com**。
2. 打开 **开发者工具（F12）** → **网络** 选项卡。
3. 点击任意到 `x.com` 的请求（例如 `HomeTimeline`）。
4. 在 **请求头部** 下，找到 **`cookie:`** 并复制整个值。
5. 输入：
```bash
tweetkit import --paste
# 粘贴 cookie 头部，然后按 Ctrl-D
```
### 方法 B — F12 "保留日志" HAR 文件
1. 在 **已登录** 的情况下打开 **x.com** → **开发者工具（F12）** → **网络**。
2. 勾选 **"保留日志"**，然后重新加载/点击周围以捕获请求。
3. **右键任意请求 → "将所有内容保存为 HAR"** （或使用 ⬇ 出口图标）。
4. 导入：
```bash
tweetkit import --file ~/Downloads/x.com.har
```
> 现代 Chrome 可能会从导出的 HAR 中 **删除 cookie**。如果 tweetkit 报告 `auth_token` 丢失，请在网络设置中启用 **"允许生成带有敏感数据的 HAR"**，或回退到 **方法 A** / **方法 C**。
### 方法 C — **storagedump** 浏览器扩展（zip）
最简单的无需开发者工具的路由。 **[storagedump](https://chromewebstore.google.com/detail/storagedump/kihoghfekemdccfnpjefmggehpgnjnab)** （由该项目的作者构建的 Chrome 扩展程序）导出一个选项卡的浏览器存储 — 包括 **HttpOnly** `auth_token`，而 `document.cookie` 无法访问 — 作为包含 `cookies.json` 的 `.zip` 文件。在 x.com（已登录）上，点击扩展程序 → 导出，然后：
```bash
tweetkit import --file storagedump_x.com_2026-07-05.zip
```
tweetkit 读取扩展程序的原生格式， `{ "data": [ { "key": "...", "value": "..." }, ... ] }`，并且也接受纯列表或 `{name: value}` 映射。Cookie-Editor / EditThisCookie JSON 导出（`--file export.json`）也有效。
> 安装： **[Chrome 应用商店上的 storagedump](https://chromewebstore.google.com/detail/storagedump/kihoghfekemdccfnpjefmggehpgnjnab)**。
### 会话 cookie 存储位置
默认情况下，`tweetkit import` 写入 **`~/.config/tweetkit/cookie.txt`** （chmod `600`；同时 git-ignored）。您更喜欢 **macOS 钥匙串**？添加 `--keychain <slug>`：
```bash
tweetkit import --paste --keychain tweetkit
export TWEETKIT_COOKIE_KEYCHAIN=tweetkit
```
运行时解析顺序（第一个命中优先）：显式参数 → `TWEETKIT_COOKIE` → `TWEETKIT_COOKIE_FILE` → `./cookie.txt` → `~/.config/tweetkit/cookie.txt` → 钥匙串（`TWEETKIT_COOKIE_KEYCHAIN`）。
---
## Python 用法
```python
from tweetkit_x import TweetKit
tk = TweetKit(keychain_slug="tweetkit") # 或 cookie="auth_token=...; ct0=..."
tk.whoami() # {'ready': True, 'user_id': '...', 'ct0_len': 160}
# 发布
tk.post("你好，世界")
tk.post("带图片", image_path="chart.png")
tk.post("回复", reply_to="1800000000000000000")
# 线程 — 字符串或（文本，图像路径）元组；每个都回复前一个
tk.post_thread(["1/ 介绍", ("2/ 图表", "chart.png"), "3/ 结尾"])
# 读取
mine = tk.get_tweets(limit=100) # 您的推文，新鲜的
theirs = tk.get_tweets(username="jack", limit=50) # 任何人的
# 搜索（本地过滤时间线 - 无需付费搜索 API）
hits = tk.search("monero") # 子字符串
hits = tk.search(r"xmr|monero", regex=True) # 正则表达式
# 删除
tk.delete("1800000000000000000")
tk.delete_many([t["id"] for t in hits])
# 引用推文
tk.quote("这很棒", quote_tweet_id="1800000000000000000")
# 互动（每个都有撤销）
tk.like("1800000000000000000"); tk.unlike("1800000000000000000")
tk.retweet("1800000000000000000"); tk.unretweet("1800000000000000000")
tk.bookmark("1800000000000000000"); tk.unbookmark("1800000000000000000")
# 读取单个推文，并搜索整个 X（真实搜索 + 运算符）
tk.get_tweet("1800000000000000000")
tk.search_x("mcp 服务器", latest=True, limit=40)
tk.search_x("from:jack min_faves:1000") # X 搜索运算符有效
```
每次写入操作都返回 `{'ok': True, 'id': '...', 'url': '...'}` 表示成功，或 `{'ok': False, 'status': ..., 'error': '...'}` 表示失败 — 方便日志记录或重试。
参阅 [`examples/`](examples/) 了解完整的 "查找我的 $XMR 推文并删除它们" 清理循环。
---
## 命令行用法
```bash
tweetkit whoami
tweetkit post "只是一些文本"
tweetkit post "文本 + 媒体" --image pic.png
tweetkit post "回复" --reply-to 1800000000000000000
tweetkit thread thread.txt # 推文由空行分隔
tweetkit delete 1800000000000000000 1800000000000000001
tweetkit tweets --limit 100 # 您的推文
tweetkit tweets @jack --limit 50 # 其他人的推文
tweetkit search monero # 您的推文中包含 "monero"
tweetkit search "xmr|monero" --regex
tweetkit searchx "mcp 服务器" --latest # 搜索整个 X（真实搜索 + 运算符）
tweetkit get 1800000000000000000 # 通过 ID 获取单个推文
tweetkit quote "优秀的线程" 1800000000000000000
tweetkit like 1800000000000000000 # 还有：unlike / retweet / unretweet / bookmark / unbookmark
```
`thread.txt` 只是一个由 **空行** 分隔的推文。
---
## MCP 服务器
tweetkit 附带一个一流的 **MCP 服务器**，以便 AI 客户端可以为您发布/删除/读取 — 并 **引导用户进行身份验证**，解释 cookie 并通过一次粘贴设置 cookie。
### 配置您的客户端
**Claude Desktop / Claude Code / Cursor** — 添加到您的 MCP 配置（`claude_desktop_config.json`，`.mcp.json`，...）：
```jsonc
{
"mcpServers": {
"tweetkit": {
"command": "uvx",
"args": ["--from", "tweetkit-x[mcp]", "tweetkit-mcp"],
"env": { "TWEETKIT_COOKIE_KEYCHAIN": "tweetkit" }
}
}
}
```
如果已经 `pip install` 了？直接使用控制台脚本：
```jsonc
{ "mcpServers": { "tweetkit": { "command": "tweetkit-mcp",
"env": { "TWEETKIT_COOKIE_KEYCHAIN": "tweetkit" } } } }
```
如果您没有设置任何 cookie 环境变量，那也没关系 — 服务器以未经身份验证的状态启动，并要求用户从聊天中设置 cookie（如下所示）。
### 无缝身份验证，从聊天中
服务器 **描述每个值** 并提供最低努力的路径。一个典型的首次运行：
1. 客户端调用 **`auth_status`** → *未身份验证*。
2. 服务器的说明告诉助手要求您提供 cookie 并解释 **什么是 `auth_token` 和 `ct0`** 以及如何复制它们。
3. 您粘贴 `Cookie:` 头部一次 → **`set_session_cookie("<paste>")`** → 存储（钥匙串或文件）并激活。或指向 **`import_cookie_from_file("~/Downloads/x.com.har")`** 到 HAR / 存储转储 zip。
原始 cookie 永远不会被回显。
### 工具
| 工具 | 功能 |
|---|---|
| `auth_status` | 是否加载了有效的会话？（首先调用） |
| `set_session_cookie(cookie_header)` | 从粘贴的 `Cookie:` 头部设置身份验证 — 解释确切要复制的内容 |
| `import_cookie_from_file(path)` | 从 HAR / 存储转储 `.zip` / cookie JSON 设置身份验证 |
| `post_tweet(text, image_path?, reply_to?)` | 发布推文（可选图像/回复） |
| `post_thread(tweets[])` | 发布线程 |
| `quote_tweet(text, quote_tweet_id, image_path?)` | 引用现有的推文 |
| `delete_tweet(tweet_id)` / `delete_tweets(ids[])` | 删除推文 |
| `like_tweet` / `unlike_tweet` / `retweet` / `unretweet` / `bookmark_tweet` / `unbookmark_tweet` | 互动（每个都可撤销） |
| `get_my_tweets(limit?)` / `get_user_tweets(username, limit?)` | 读取时间线 |
| `get_tweet(tweet_id)` | 通过 ID 获取单个推文 |
| `search_my_tweets(query, regex?, limit?)` | 查找您自己的推文（本地过滤 - 非常适合清理） |
| `search_x(query, latest?, limit?)` | 搜索 **整个 X**（真实搜索，支持运算符） |
| `post_note` / `schedule_tweet` / `unschedule_tweet` | 长格式笔记推文；安排/取消 |
| `follow_user` / `unfollow_user` / `block_user` / `unblock_user` / `mute_user` / `unmute_user` | 社交图操作 |
| `pin_tweet` / `unpin_tweet` | 固定 / 取消固定到您的个人资料 |
| `get_home_timeline` / `get_replies` / `get_notifications` / `get_bookmarks` | 时间线和对话 |
| `get_user_profile` / `get_followers` / `get_following` / `get_likers` / `get_retweeters` / `get_user_likes` | 人物与个人资料 |
> **不支持（暂时）：** DM，投票（创建/投票），列表，个人资料编辑，空间，隐藏回复。这些需要捕获确切操作的 HAR 文件来确定端点 — 欢迎请求添加。
---
## 工作原理
当你在浏览器中操作时，x.com 调用少数内部端点。tweetkit 1:1 复制它们：
1. **`x-client-transaction-id`** — X 需要一个源自页面 `ondemand.s` JS 和主页提取的防机器人头部。 使用独立的 [`x-client-transaction-id`](https://pypi.org/project/x-client-transaction-id/) 包生成。
2. **图像上传** （图片）— `POST upload.x.com/i/media/upload.json` 作为 `INIT` → `APPEND` → `FINALIZE`，得出一个 `media_id`。
3. **写入/删除** — `POST /i/api/graphql/<queryId>/CreateTweet` 和 `.../DeleteTweet`。
4. **读取** — `GET /i/api/graphql/<queryId>/UserTweets` （按光标分页），以及 `UserByScreenName` 以解析 `@handles`。
身份验证仅需您的 **cookie** + 公共网络 **bearer** 令牌（与 x.com 嵌入的相同非秘密 bearer 令牌）+ 作为 `x-csrf-token` 回声的 **`ct0`** CSRF 值。
```
您的 cookie ──► x-client-transaction-id ──► CreateTweet / DeleteTweet / UserTweets ──► 结果
```
> GraphQL **查询 ID** 位于 [`tweetkit_x/constants.py`](tweetkit_x/constants.py)。X 每隔几周轮换一次；如果调用开始失败，请从新的 HAR 中刷新它们（该文件有逐步说明）。
---
## 安全
- cookie 是唯一的机密。它存储在 **chmod 600** 的 `~/.config/tweetkit/cookie.txt` 或 macOS **钥匙串** 中，并且 `.gitignore` 阻止了 `cookie.txt`、`.env`、*.har 和 *.zip。
- tweetkit **从不打印** cookie 值；导入程序仅报告找到哪些 cookie 及其长度。
- 捆绑的 **bearer** 与 X 的公共网络 bearer 相同，对于每个访问者来说都是相同的 — 不是秘密。
---
## 免责声明
本项目自动化您自己的 X 网络会话用于 **个人** 用途。自动执行网络会话 **违反 X 服务条款**，使用它可能会使您的帐户面临限流、暂停或封禁的风险。 **您完全负责** 您如何使用它。按原样提供，**不保证**。与 X Corp. 无关。
## 许可
[MIT](LICENSE) © 2026 ns0bj
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器