tweetkit-x

tweetkit-x

使用你自己的已登录浏览器会话，通过 Python 和 MCP 服务在 X（Twitter）上发布、删除和阅读。
无需付费 API。无需开发者应用。无需繁琐的 OAuth 流程。只需你的会话 Cookie。

快速开始 · 获取你的 Cookie · Python · CLI · MCP 服务 · 工作原理 · 免责声明

---

为什么

自 2026 年 2 月 6 日起，X 官方 API 对新开发者不再提供免费套餐，而是按使用量付费：每条帖子约 0.015 美元，带链接的帖子约 0.20 美元，此外还有按读取量收取的费用。对于发布你自己的推文（发布你内容的机器人、定时帖子串，或删除旧帖子的清理脚本），这意味着你要为一项浏览器本来就能免费完成的操作持续付费。

tweetkit-x 完全绕过 API。它会重放你点击发布、删除或滚动浏览个人主页时，浏览器发出的完全相同的内部 HTTP 请求，并使用你已有的会话 Cookie 进行身份验证。发布、删除并读取完整时间线，无需支付 API 费用。

⚠️ 自动化你的 Web 会话违反 X 的服务条款。这是用于个人自动化的灰色地带工具。账号风险完全由你自行承担。 请参阅免责声明。

---

功能

• ✅ 发布 — 文本、最多 4 张图片、GIF 和视频（支持替代文本）、回复、帖子串、引用推文、长文笔记推文和定时推文
• 🗑️ 删除 — 单个 ID、ID 列表，或循环执行“查找匹配项并删除”进行清理
• ❤️ 互动 — 点赞、转推、收藏、关注、屏蔽、静音、置顶——每项操作都可撤销
• 🌐 搜索 X 全站内容 — 使用真正的 SearchTimeline（支持 from:、min_faves:、filter:media 等运算符），还可对你自己的推文使用本地正则表达式搜索
• 📖 阅读 — 你的主页信息流、任意时间线、推文的回复/对话、粉丝/关注对象、点赞者/转推者、书签、用户的点赞内容、通知和完整个人资料
• 🔌 MCP 服务 — 40 个工具；可接入 Claude Desktop / Claude Code / Cursor；提供可说明 Cookie并通过一次粘贴完成设置的工具
• 🔑 轻松完成身份验证 — 粘贴 Cookie: 请求头，导入 HAR 文件或 storage-dump zip；可将 Cookie 存入文件或 macOS Keychain
• 🐍 Python API 和 CLI（tweetkit …）
• 🪶 体积小巧——无需无头浏览器或 Selenium

---

快速开始

pip install "tweetkit-x[mcp]"      # or: pip install tweetkit-x   (library + CLI only)

# 1. Import your session cookie (three ways — see the next section)
tweetkit import --paste                       # paste the Cookie: header, Ctrl-D
#   or:  tweetkit import --file x.com.har
#   or:  tweetkit import --file storagedump_x.com.zip --keychain tweetkit

# 2. Verify (no network call)
tweetkit whoami
# {"ready": true, "user_id": "1986...", "ct0_len": 160}

# 3. Use it
tweetkit post "hello world 👋"
tweetkit search "xmr|monero" --regex          # your tweets that match
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. 打开 DevTools（F12） → Network 标签页。
3. 点击任意一条发往 x.com 的请求（例如 HomeTimeline）。
4. 在 Request Headers 下找到 cookie:，并复制完整值。
5. 将其传入：

tweetkit import --paste
# paste the cookie header, then press Ctrl-D

方法 B——使用 F12 的“Preserve log” HAR 文件

1. 登录后打开 x.com → DevTools（F12） → Network。
2. 勾选 “Preserve log”，然后重新加载页面／点击几处内容以捕获请求。
3. 右键点击任意请求 → “Save all as HAR”（或使用 ⬇ 导出图标）。
4. 导入：

tweetkit import --file ~/Downloads/x.com.har

现代版 Chrome 可能会从导出的 HAR 中移除 Cookie。如果 tweetkit 提示缺少 auth_token，请在 Network 设置中启用 “Allow to generate HAR with sensitive data”，或改用方法 A／方法 C。

方法 C——使用 storagedump 浏览器扩展（zip）

最简单的免用 DevTools 方法。storagedump（由本项目作者开发的 Chrome 扩展）可导出标签页的浏览器存储内容——包括 document.cookie 无法读取的 HttpOnly auth_token——并生成包含 cookies.json 的 .zip 文件。在已登录的 x.com 上，点击扩展 → 导出，然后：

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。

Cookie 的存储位置

默认情况下，tweetkit import 会写入 ~/.config/tweetkit/cookie.txt（权限为 600；也已加入 git 忽略列表）。更倾向于使用 macOS Keychain？请添加 --keychain <slug>：

tweetkit import --paste --keychain tweetkit
export TWEETKIT_COOKIE_KEYCHAIN=tweetkit

运行时的解析顺序（采用第一个匹配项）：显式参数 → TWEETKIT_COOKIE → TWEETKIT_COOKIE_FILE → ./cookie.txt → ~/.config/tweetkit/cookie.txt → Keychain（TWEETKIT_COOKIE_KEYCHAIN）。

---

Python 用法

from tweetkit_x import TweetKit

tk = TweetKit(keychain_slug="tweetkit")          # or cookie="auth_token=...; ct0=..."

tk.whoami()                                       # {'ready': True, 'user_id': '...', 'ct0_len': 160}

# post
tk.post("hello world")
tk.post("with a picture", image_path="chart.png")
tk.post("a reply", reply_to="1800000000000000000")

# thread — strings or (text, image_path) tuples; each replies to the previous
tk.post_thread(["1/ intro", ("2/ chart", "chart.png"), "3/ outro"])

# read
mine = tk.get_tweets(limit=100)                   # your tweets, newest first
theirs = tk.get_tweets(username="jack", limit=50) # anyone's

# search (local filter over the timeline — no paid search API)
hits = tk.search("monero")                        # substring
hits = tk.search(r"xmr|monero", regex=True)       # regex

# delete
tk.delete("1800000000000000000")
tk.delete_many([t["id"] for t in hits])

# quote-tweet
tk.quote("this is great", quote_tweet_id="1800000000000000000")

# engage (each has an undo)
tk.like("1800000000000000000");     tk.unlike("1800000000000000000")
tk.retweet("1800000000000000000");  tk.unretweet("1800000000000000000")
tk.bookmark("1800000000000000000"); tk.unbookmark("1800000000000000000")

# read a single tweet, and search ALL of X (real search + operators)
tk.get_tweet("1800000000000000000")
tk.search_x("mcp server", latest=True, limit=40)
tk.search_x("from:jack min_faves:1000")     # X search operators work

每次写入成功时都会返回 {'ok': True, 'id': '...', 'url': '...'}，失败时则返回 {'ok': False, 'status': ..., 'error': '...'}——便于记录日志或重试。

请参阅 examples/，了解一个完整的“查找并删除我的 $XMR 推文”清理循环。

---

CLI 用法

tweetkit whoami
tweetkit post "just some text"
tweetkit post "text + media" --image pic.png
tweetkit post "a reply" --reply-to 1800000000000000000
tweetkit thread thread.txt                 # tweets separated by blank lines
tweetkit delete 1800000000000000000 1800000000000000001
tweetkit tweets --limit 100                # your tweets
tweetkit tweets @jack --limit 50           # someone else's
tweetkit search monero                     # your tweets containing "monero"
tweetkit search "xmr|monero" --regex
tweetkit searchx "mcp server" --latest     # search ALL of X (real search + operators)
tweetkit get 1800000000000000000           # one tweet by id
tweetkit quote "great thread" 1800000000000000000
tweetkit like 1800000000000000000          # also: unlike / retweet / unretweet / bookmark / unbookmark

thread.txt 只需用空行分隔推文。

---

MCP 服务

tweetkit 提供一流的 MCP 服务，让 AI 客户端可以替你发布／删除／读取内容——并且会引导用户完成身份验证，说明 Cookie 是什么，并通过一次粘贴完成设置。

配置客户端

Claude Desktop / Claude Code / Cursor——将以下内容添加到你的 MCP 配置中（claude_desktop_config.json、.mcp.json 等）：

{
  "mcpServers": {
    "tweetkit": {
      "command": "uvx",
      "args": ["--from", "tweetkit-x[mcp]", "tweetkit-mcp"],
      "env": { "TWEETKIT_COOKIE_KEYCHAIN": "tweetkit" }
    }
  }
}

已经运行过 pip install？可直接使用控制台脚本：

{ "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>") → 保存（Keychain 或文件）并激活。或者，将 HAR / 存储转储 zip 文件传给 import_cookie_from_file("~/Downloads/x.com.har")。

原始 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	用户与个人资料

**暂不支持：**私信、投票（创建 / 投票）、列表、编辑个人资料、Spaces、隐藏回复。这些功能需要捕获对应操作的 HAR 来确定接口 — 可按需轻松添加。

---

工作原理

你在浏览器中操作时，x.com 会调用少数几个内部接口。tweetkit 会逐一复现这些接口：

1. x-client-transaction-id — X 要求提供一个反机器人请求头，该请求头基于页面的 ondemand.s JS 和一次主页抓取生成。由独立的 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（通过游标分页），以及用于解析 @handles 的 UserByScreenName。

身份验证只需要你的 Cookie + 公开的 Web bearer 令牌（嵌入在 x.com 中、所有访客共用的同一个非机密 bearer 令牌）+ 作为 x-csrf-token 回传的 ct0 CSRF 值。

your cookie ──► x-client-transaction-id ──► CreateTweet / DeleteTweet / UserTweets ──► result

GraphQL 查询 ID 位于 tweetkit_x/constants.py 中。X 每隔几周就会轮换这些 ID；如果某个调用开始失败，请从新捕获的 HAR 中刷新它们（文件中包含逐步说明）。

---

安全性

• Cookie 是唯一的机密信息。它以 chmod 600 的权限保存在 ~/.config/tweetkit/cookie.txt 或 macOS Keychain 中，且 .gitignore 会排除 cookie.txt、.env、*.har 和 *.zip。
• tweetkit 绝不会打印 Cookie 值 — 导入工具只会报告找到的 Cookie 名称及其长度。
• 随附的 bearer 是 X 的公开 Web bearer 令牌，所有访客都相同 — 不属于机密信息。

---

免责声明

本项目会自动化操作你自己的 X 网页会话，供个人使用。自动化操作网页会话违反 X 的服务条款，使用本项目可能导致你的账号受到速率限制、暂停或封禁。你须对自己的使用方式承担全部责任。本项目按原样提供，不作任何担保。与 X Corp. 无关联。

许可证

MIT © 2026 ns0bj