FastMCP server for Substack — publish Notes and posts, pull analytics, manage dr

substack-mcp

用于 Substack 的 FastMCP 服务：发布 Notes 和文章、获取分析数据、管理草稿、将 Obsidian 库草稿同步到 Substack，并通过可插拔的图像生成器生成视觉卡片。

快速参考

substack__test_connection             -- verify auth (start here)
substack__publish_note text=...       -- publish a Note immediately
substack__list_vault_drafts           -- show drafts from your vault file
substack__publish_vault_draft index=N -- publish one vault draft as a Note
substack__create_draft title=... body=... -- create a post draft
substack__get_dashboard days=30       -- subscriber + view KPIs
substack__capture_analytics_to_vault  -- snapshot analytics to vault markdown

工具列表（30）

Notes + 知识库工作流

• test_connection(publication?) -- 验证身份验证并返回个人资料
• list_publications() -- 显示已配置的出版物及默认出版物
• publish_note(text, publication?, attachment_ids?) -- 立即发布 Note；支持 Markdown
• create_note_attachment(image_path?, image_url?, link_url?, publication?) -- 上传图片或注册链接；返回可用于 publish_note 的附件 UUID
• list_my_notes(limit?, publication?) -- 查看最近的 Notes 及其反应和评论数
• reply_to_note(note_id, text, publication?) -- 按 ID 回复 Note
• list_vault_drafts() -- 解析知识库草稿文件，并返回每篇草稿的索引和预览
• publish_vault_draft(index, publication?, move_to_published?) -- 将一篇知识库草稿作为 Note 发布
• batch_publish_vault_drafts(indices, publication?) -- 按顺序发布多篇知识库草稿

文章管理

• create_draft(title, body, subtitle?, audience?, publication?, section_id?) -- 创建文章草稿；正文为 Markdown
• update_draft(draft_id, title?, body?, subtitle?, audience?, publication?, section_id?) -- 编辑现有草稿
• publish_post(draft_id, send_email?, audience?, publication?, section_id?) -- 向订阅者正式发布草稿
• schedule_post(draft_id, publish_at, publication?, section_id?) -- 安排草稿在未来发布（ISO 8601）
• list_sections(publication?) -- 列出出版物已配置的版块；在包含版块的出版物上发布文章时必须使用
• list_drafts(limit?, publication?) -- 列出未发布的草稿
• list_published(limit?, publication?) -- 列出已发布的文章及基本统计数据
• get_post(identifier, publication?) -- 按 slug 或数字 ID 获取完整文章
• upload_image(image_path, publication?) -- 将图片上传到 Substack CDN；返回 CDN URL
• react(post_id, publication?) -- 为文章点赞
• restack(post_id, publication?) -- 转发文章
• comment(post_id, body, publication?) -- 评论文章
• get_feed(limit?, publication?) -- 获取你的阅读动态（来自你关注的出版物的文章）

分析

• get_dashboard(days?, publication?) -- KPI：订阅者总数/付费订阅者、浏览量、增长、ARR
• get_post_stats(post_id, publication?) -- 单篇文章的浏览量、打开次数、点击次数、分享次数、转化次数
• get_subscriber_growth(publication?) -- 随时间变化的订阅者数量
• get_growth_sources(publication?) -- 按来源统计的订阅者增长（搜索、推荐、直接访问、社交媒体）
• get_top_posts(limit?, publication?) -- 按互动度排名的文章
• get_earnings(publication?) -- 付费出版物的收入数据
• get_recommendation_stats(direction?, publication?) -- 推荐网络表现
• capture_analytics_to_vault(publication?) -- 将每周分析快照写入你的知识库

安装

打开 Claude Code，粘贴：

/plugin marketplace add adelaidasofia/substack-mcp
/plugin install substack-mcp@substack-mcp

git clone https://github.com/adelaidasofia/substack-mcp
cd substack-mcp
pip3 install -r requirements.txt
python3 -c "import server; print('OK')"

配置

将 config.example.json 复制为 config.json，并填写你的值：

cp config.example.json config.json

config.json 已加入 gitignore。关键字段：

设置会话 Cookie

Substack 没有提供使用 OAuth 的公共 API。身份验证使用你的浏览器会话 Cookie。

1. 打开 Chrome 并登录 Substack。
2. 打开开发者工具（F12），然后转到 Application 标签页。
3. 在 Cookies 下找到 substack.com。
4. 复制 substack.sid 的值。
5. 将其粘贴到 config.json 中对应出版物的 cookie 字段。

原始值即可使用；服务端接受 abc123 和 substack.sid=abc123 两种格式。

会话 Cookie 会过期。如果工具返回 {"error": "Auth failed"}，请重新提取 Cookie。

在 Claude Code 中注册

添加到你的 .mcp.json（项目范围），或通过 claude mcp add -s user 添加：

{
  "mcpServers": {
    "substack": {
      "command": "python3",
      "args": ["/path/to/substack-mcp/server.py"]
    }
  }
}

编辑 .mcp.json 后重启 Claude Code。使用 claude mcp list 验证。

知识库集成

在 config.json 中将 vault_drafts_path 设置为 Obsidian 知识库中的 Markdown 文件。 每篇草稿格式为一个由 --- 分隔的章节。## Ready to Post 下的章节会优先显示在 list_vault_drafts 的结果中。接下来显示 ## Essay Seeds 下的章节。

发布后，publish_vault_draft 会将草稿移至 ## Published 章节， 并附上 Substack URL 和时间戳。

可插拔图像生成器

视觉卡片的生成由 config.json 中 image_generator.default 所指定的适配器负责。

附带的适配器

pillow_local（默认）-- 纯 Pillow，不需要外部 API。它会使用 fonts/ 目录中的字体， 在本地渲染 1080x1080 PNG 卡片。提供三种支柱模板：暖芥末黄配可选人物（P1）、深酒红色粗体引文（P2）、芥末黄配章节标签（P3）。可将 render_card.py 作为独立 CLI 使用。

canva -- Canva MCP 编排。返回一个 steps 列表，描述克隆模板、替换文本、替换人物和导出 PNG 所需的 Canva MCP 工具调用。执行此操作手册的 Claude 会话会按步骤操作。要求 Canva MCP 已连接到 Claude Code，并在 image_generator.canva.pillars 下填写设计 ID。

桩式适配器（欢迎贡献）

nano_banana —— 通过 nano-banana skill 使用 Gemini 3 Pro Image。桩位于 image_generators/nano_banana.py。通过调用 skill 的图像端点，并使用根据卡片规格构建的 提示词，实现 generate()。

midjourney —— Midjourney API（或代理）。桩位于 image_generators/midjourney.py。 通过提交提示词、轮询完成状态并下载结果，实现 generate()。

dalle —— OpenAI DALL-E。桩位于 image_generators/dalle.py。使用 openai.images.generate 实现 generate()。

编写自己的适配器

从 image_generators.base 中的 ImageGenerator 派生子类：

from image_generators.base import ImageGenerator

class MyAdapter(ImageGenerator):
    @property
    def name(self) -> str:
        return "my_adapter"

    def generate(self, spec: dict) -> dict:
        # spec keys: pillar, quote, handle, figure_path, output_path
        # return: {status: "ok", adapter: ..., image_path: ..., width: ..., height: ...}
        ...

在 image_generators/__init__.py 中注册，并在 config.json 的 image_generator.my_adapter 下添加配置块。

可视化发布流水线

visual_helper.py 脚本处理可视化队列流水线中的确定性任务：解析 Review Queue Markdown 文件、轮换图像，并标记已发布的条目。完整端到端流程（包括图像生成、上传和发布步骤）请参见 visual_playbook.md。

python3 visual_helper.py peek --lang es        # get next approved visual item
python3 visual_helper.py mark --lang es ...    # mark published + update log
python3 visual_helper.py rotate-figure --pillar P1

已知注意事项

1. Cookie 过期。 substack.sid Cookie 会在几周后过期。当 test_connection 返回身份验证错误时，请从 Chrome DevTools 重新提取。

2. draft_bylines 是必需的，但文档未说明。 如果没有它，create_draft 会返回 400。 服务会自动从 /user/profile/self 获取你的 user_id，并将其注入每个草稿 POST 请求。

3. 笔记附件端点要求路径末尾带斜杠。 POST /comment/attachment/（带斜杠）可正常工作。不带斜杠会返回 404。服务已正确处理此问题。

4. Publication 范围端点与全局端点。 笔记使用 substack.com/api/v1/comment/feed/。 文章草稿使用 {subdomain}.substack.com/api/v1/drafts。混用会返回 404 或 403。

5. 仪表板中的 pledgedArr 是投影数据，并非实际承诺金额。 请使用 get_earnings 获取实际收入数据。

6. 支持多个 publication。 向任何工具传入 publication="name"，即可指定目标 publication。省略此参数则使用配置中的 default_publication。

7. 对于设有分区的 publication，发布时必须指定分区。 如果草稿尚未归入某个分区，Substack 会在 publish_post / schedule_post 中返回 HTTP 400: Please choose a section。使用 list_sections(publication="main") 查找分区 ID，然后将 section_id=<id> 传给草稿工具或发布／安排工具：

   list_sections                             # → [{id: 12345, name: "Essays", slug: "essays", ...}, ...]
   create_draft title=... body=... section_id=12345
   # or, for an existing draft:
   publish_post draft_id=987654 section_id=12345
   

   publish_post / schedule_post 会在发布前更新草稿，因此调用一次即可。

相关 MCP

同一作者，采用相同的架构模式（FastMCP、适用时写入操作采用草稿 + 确认、自动导出到知识库、MIT）：

• slack-mcp — 多工作区 Slack
• imessage-mcp — macOS iMessage
• whatsapp-mcp — 通过 whatsmeow 使用 WhatsApp
• google-workspace-mcp — Gmail / Calendar / Drive / Docs / Sheets
• apollo-mcp — Apollo.io CRM + 序列
• luma-mcp — lu.ma 活动
• parse-mcp — markitdown / Docling / LlamaParse 路由器
• rescuetime-mcp — RescueTime 效率数据
• graph-query-mcp — 知识库知识图谱查询
• graph-autotagger-mcp — 根据知识图谱生成 wikilink 建议
• investor-relations-mcp — 种子轮融资流程跟踪器
• vault-sync-mcp — 双向知识库同步

遥测

此插件会在某台机器上的 Claude Code 会话中首次加载时，向 myceliumai.co 发送一次匿名安装信号。

发送的内容：

• 插件名称（例如 slack-mcp）
• 插件版本（例如 0.1.0）

不会发送的内容：

• 不会发送用户标识符、姓名、电子邮件、令牌或 API 密钥
• 不会发送文件路径、消息内容或任何与你的工作相关的信息
• 去重处理后不会存储 IP 地址

原因： 帮助维护者了解用户实际安装了哪些插件，从而将精力投入到有人使用的插件上。

选择退出： 在启动 Claude Code 前设置环境变量 MYCELIUM_NO_PING=1。钩子将完全跳过网络调用。已发送过信号的安装会在 ~/.mycelium/onboarded-<plugin> 留下一个标记文件——如果想重置状态，请将其删除。

许可证

MIT

由 Mycelium AI 构建。完整安装版或团队版请访问 diazroa.com。