substack-mcp

一个用于 Substack 的模型上下文协议 (MCP) 服务器。允许 Claude Code 在您的 Substack 出版物上创建草稿、上传图片、设置封面缩略图、定时发布和发布文章。

基于 python-substack 构建。 使用 Substack 的内部 API（不存在公开的发布 API）。与 Substack Inc. 无关联。

工具

必需

• create_draft(title, content_markdown, subtitle?, audience?) — 从 Markdown 创建新草稿。

• update_draft(post_id, title?, subtitle?, content_markdown?, audience?) — 编辑现有草稿。

• upload_image(image_path) — 将本地文件或远程 URL 上传到 Substack 的 CDN，并返回 URL。

• publish_draft(post_id, send_email?, share_automatically?) — 立即发布。send_email 用于切换是否发送邮件。

推荐

• schedule_draft(post_id, iso_datetime) — 安排在未来日期/时间发布（ISO 8601 格式）。

• unschedule_draft(post_id) — 取消定时发布。

• set_cover_image(post_id, image_url) — 设置封面缩略图（使用 upload_image 返回的 URL）。

实用工具

• list_drafts(limit?) — 列出最近的草稿。

• get_draft(post_id) — 获取草稿的完整正文。

• delete_draft(post_id) — 永久删除。

设置

# 1. Install dependencies
uv pip install -e .

# 2. Make sure you're logged in to Substack in Chrome (or Brave/Edge) — that's it.

# 3. Save credentials — auto-detects your existing browser session
substack-mcp-setup

# 4. Register with Claude Code
claude mcp add substack-mcp --scope user -- /Users/$USER/substack/.venv/bin/substack-mcp

重启 Claude Code，然后 /mcp 应该会显示 substack-mcp 为 connected（已连接）。

身份验证的工作原理

默认情况下，substack-mcp-setup 会通过 pycookiecheat 直接从您现有的 Chrome 会话中读取 substack.sid cookie。Substack 无法察觉任何自动化行为，因为根本没有自动化：它使用的就是您已经在使用的同一个会话。

macOS 会提示一次以获取钥匙串访问权限（“Chrome Safe Storage”）。请点击“始终允许”，这样下次就不会再询问了。

支持：Chrome、Brave、Edge、Chromium、Vivaldi、Opera。

回退模式

# Specific browser
substack-mcp-setup --from-browser brave

# Playwright-based (often blocked by Substack — use --chrome instead)
substack-mcp-setup --browser

# Manual paste from DevTools
substack-mcp-setup --manual

令牌存储在 ~/Library/Application Support/substack-mcp/config.json 中，权限为 0600。

安全性

substack.sid cookie 等同于密码 — 任何拥有它的人都拥有完整的账户访问权限（发布文章、编辑账单等）。请妥善保管。

令牌存储位置

• macOS: ~/Library/Application Support/substack-mcp/config.json (模式 0600)

• Linux: ~/.config/substack-mcp/config.json (模式 0600)

• 或通过环境变量: SUBSTACK_PUBLICATION_URL + SUBSTACK_SESSION_TOKEN (环境变量会被子进程继承 — 在生成子进程时请注意)

.gitignore 已排除 config.json；切勿将其提交到版本控制中。MCP 还会通过 tempfile.mkstemp (模式 0600) 写入一个临时 cookie 文件，并在 finally 块中将其删除 — 请参阅 auth.py:write_cookie_file。

如果令牌泄露

1. 退出所有会话：Substack → 设置 → 安全 → “退出所有会话”。这将立即让所有现有的 substack.sid 失效。

2. 在浏览器中重新登录 Substack。

3. 重新运行 substack-mcp-setup 以获取新的 cookie。

图片上传安全性

upload_image 仅接受：

• HTTP(S) URL，或

• 具有图片扩展名（.png, .jpg, .jpeg, .gif, .webp, .heic, .heif）且不在敏感系统路径（/etc, /System, ~/.ssh, ~/.aws, ~/Library/Keychains 等）下的本地文件。

这可以防止助手被诱导（通过获取内容中的提示注入）上传例如 SSH 私钥到 Substack 的 CDN。

已知限制：create_draft 内部的 Markdown 图片语法 ![alt](path) 由 python-substack 处理，并绕过了此验证。如果您传递不可信的 Markdown，请先清理图片路径。

依赖项

版本使用 ~=（兼容版本，无重大更新）进行锁定。特别是升级 python-substack 时应进行审查 — 它与 Substack 的私有 API 通信，且不在 Substack 的官方支持范围内。

注意事项

• audience 接受：everyone（默认）、only_paid、founding、only_free。

• 当您调用 create_draft 时，Markdown 图片语法 ![alt](path/or/url) 会自动上传本地文件。

• 封面图片（通过 set_cover_image 设置）会显示在您的出版物主页和社交分享中。如果您没有明确设置，Substack 通常会使用正文中的第一张图片。