MCP协议实战：用AI助手一键发布Substack文章
1. 项目概述：一个连接AI与创作平台的桥梁
最近在折腾AI工作流，发现一个痛点：很多AI工具生成的内容很棒，但想把它一键发布到像Substack这样的付费订阅平台，流程总是很割裂。要么手动复制粘贴，要么依赖一些不稳定的浏览器插件。直到我发现了这个叫dkships/substack-publisher-mcp的项目，眼前才一亮。本质上，它是一个MCP（Model Context Protocol）服务器，专门为AI助手（比如Claude Desktop、Cursor等）添加了直接操作Substack的能力。
简单来说，它把你的AI助手变成了一个“全能内容运营”。你可以在和AI对话的界面里，直接让它帮你创建草稿、发布文章、管理订阅者列表，甚至分析数据。这不仅仅是省去了“复制-粘贴-点击发布”的几步操作，更是将内容创作、编辑、发布和后续管理无缝集成到了你的AI协作流程中。对于独立创作者、自媒体运营或者任何需要频繁更新Substack的人来说，这意味着生产力的巨大提升。你不用再离开你熟悉的AI对话环境，就能完成从灵感到发布的全过程。
2. MCP协议与工具生态解析
2.1 MCP是什么？为什么它是关键
要理解这个项目的价值，得先搞懂MCP。Model Context Protocol，你可以把它想象成AI世界的“USB标准”。在它出现之前，每个AI应用（如Claude、GPTs）想连接外部工具（如数据库、日历、Git），都需要开发者为其量身定制一套插件或API集成方案，非常碎片化。
MCP定义了一套标准协议，让任何符合MCP标准的“服务器”（Server）都能被任何支持MCP的“客户端”（Client）识别和使用。在这个项目里，substack-publisher-mcp就是一个“服务器”，它封装了Substack的API；而Claude Desktop、Cursor IDE就是“客户端”。一旦配置好，你的AI助手就能自动发现并调用这个Substack工具包，无需为每个AI应用单独开发插件。
注意：MCP本身不处理身份认证等安全逻辑，它主要负责工具（函数）的发现、描述和调用规范。实际的Substack API密钥等敏感信息，是在配置MCP服务器时本地管理的，这比把密钥直接交给云端AI应用要安全得多。
2.2 项目核心功能拆解
这个MCP服务器具体提供了哪些“超能力”？根据其设计，主要围绕Substack的核心操作展开：
- 内容管理：这是核心中的核心。AI可以调用工具来“创建草稿”或“直接发布文章”。你需要提供的参数通常包括标题、正文内容（支持HTML或Markdown，取决于Substack API的接受度）、子标题、播客音频URL等。更高级的是，它可能支持“更新已有文章”，让你能通过AI快速迭代和修改已发布的内容。
- 订阅者与数据分析：对于运营者来说，内容发布只是开始。理想的工具应该能帮你“列出订阅者”（可能包括分页和筛选），或者“获取帖子/简报的统计数据”（如打开率、点击率）。这能让AI不仅是个发布工具，还能成为你的数据分析助手，基于数据给你内容优化建议。
- 出版物管理：如果你管理多个Substack出版物，工具可能支持“列出我的出版物”或“切换当前默认出版物”。这样AI在操作时就能明确知道内容要发到哪里去。
这些功能通过MCP暴露为一个个具名的“工具”（Tools），AI助手在理解了你的自然语言指令后，会自动匹配并调用对应的工具完成操作。例如，你说“帮我把这篇关于量子计算的笔记发布到我的科技简报上”，AI会识别出“发布文章”的意图，并调用相应的工具函数，填入你提供的笔记内容和你之前配置好的出版物信息。
3. 实操部署与配置全指南
3.1 环境准备与依赖安装
这个项目通常是一个Node.js项目，因此你的本地环境需要先准备好Node.js（建议LTS版本，如18.x或20.x）和npm（或yarn、pnpm）。第一步永远是把代码拉到本地：
git clone https://github.com/dkships/substack-publisher-mcp.git cd substack-publisher-mcp接下来安装依赖。项目根目录的package.json文件定义了所有需要的库。除了常规依赖，关键点在于它一定包含了对@modelcontextprotocol/sdk的引用，这是开发MCP服务器的官方SDK。执行安装命令：
npm install # 或 yarn install # 或 pnpm install安装过程应该很顺畅。如果遇到网络问题，可能需要配置镜像源。一个常见的坑是，某些依赖可能需要特定的Python版本或构建工具（如node-gyp），如果你在Windows上遇到编译错误，通常需要安装Windows Build Tools或者确保你的Node.js版本与依赖兼容。
3.2 获取并配置Substack API密钥
这是整个配置中最关键也最敏感的一步。Substack官方并没有提供一个标准的、面向第三方开发的OAuth API。因此，这个MCP服务器极有可能是通过模拟浏览器登录或使用Substack的会话Cookie（session）来认证的。务必注意，这种方式需要你高度信任该项目的代码，因为它将能完全访问你的Substack账户。
通常，你需要从浏览器中登录Substack后，提取关键的Cookie值（如connect.sid）。具体步骤可能如下：
- 使用Chrome或Edge浏览器登录你的Substack账户。
- 打开开发者工具（F12），切换到“应用程序”（Application）或“存储”（Storage）标签页。
- 在左侧找到“Cookies”，点击你的Substack网站域名（如
substack.com）。 - 在右侧列表中找到名称类似
connect.sid或包含session的Cookie，将其“值”完整复制出来。
这个长字符串就是你的临时凭证。重要警告：这个Cookie具有完全的账户权限，且可能过期。切勿泄露给任何人，也不应提交到任何公开的代码仓库。
接下来，在项目根目录，你需要创建一个配置文件（如.env）或直接修改源码中的配置部分。将复制的Cookie值填入配置项，可能像这样：
# .env 文件示例 SUBSTACK_SESSION_COOKIE=你的长长session cookie字符串 SUBSTACK_PUBLICATION_URL=https://你的出版物.substack.com有些项目可能还支持配置默认的出版物ID或名称，确保发布动作能定位到正确的简报。
3.3 集成到AI客户端（以Claude Desktop为例）
配置好服务器后，需要让你的AI客户端知道它的存在。以目前对MCP支持最好的Claude Desktop为例：
- 找到Claude Desktop的配置文件夹。通常在以下位置：
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
- macOS:
- 打开这个JSON配置文件。你会看到一个
mcpServers字段。你需要将本地的MCP服务器添加进去。配置方式通常有两种：- 命令模式：指定启动服务器的命令和参数。这要求你的系统PATH能找到
node命令。
{ "mcpServers": { "substack": { "command": "node", "args": [ "/你的绝对路径/substack-publisher-mcp/build/index.js" ], "env": { "SUBSTACK_SESSION_COOKIE": "你的cookie" } } } }- 脚本模式：如果项目提供了可直接运行的脚本，路径可能更简单。
- 命令模式：指定启动服务器的命令和参数。这要求你的系统PATH能找到
- 保存配置文件，并完全重启Claude Desktop。仅仅关闭窗口可能不够，需要从任务管理器或活动监视器中彻底退出再重新启动。
重启后，当你新建一个对话，Claude应该会在界面中提示“已连接新工具：Substack Publisher”，或者你可以在输入框附近看到一个工具图标，点击能看到可用的工具列表。如果没出现，请首先检查Claude Desktop的日志文件（配置文件夹内），里面通常会有连接MCP服务器失败的具体错误信息。
4. 核心使用场景与工作流示范
4.1 场景一：从对话到发布的一键式写作
假设你正在和Claude讨论“远程工作效率工具”这个话题，并碰撞出了一份不错的大纲和内容。传统流程是：将Claude生成的内容复制到剪贴板，打开浏览器，登录Substack，新建帖子，粘贴，调整格式，点击发布。现在，整个流程可以简化为一句指令。
你可以在Claude对话中直接说：“嘿，把我们刚才讨论的关于远程工作效率工具的这三点总结，写成一篇正式的Substack文章草稿，标题就叫‘提升远程工作效率的三个被低估的工具’，并发布到我的‘数字游民指南’出版物里。”
Claude在理解指令后，会：
- 调用“撰写文章”工具。
- 自动将之前的对话历史中相关的、高质量的内容进行整理、润色，构成文章正文。
- 填充你指定的标题和出版物参数。
- 将所有这些信息通过MCP服务器发送给Substack API。
你会在Claude的回复中看到操作结果：“已在您的‘数字游民指南’出版物中创建草稿，链接为：https://xxx.substack.com/p/draft-xxx”。你可以点击链接去进行最终的人工润色和发布，或者如果配置了直接发布，文章可能已经上线。
实操心得：一开始建议先使用“创建草稿”模式，而不是“直接发布”。给自己留一个最终审核的环节。AI虽然强大，但在语气、细微观点或特定事实核查上，仍需要人的把关。将这个工具视为一个强大的副驾驶，而不是全自动驾驶。
4.2 场景二：批量管理与内容维护
除了发布新内容，这个工具在内容维护上也能发挥巨大作用。例如，你发现过去发布的某系列文章中有一个通用的错误需要修正，或者想为一系列旧文章统一添加一个新的介绍段落。
你可以对Claude说：“帮我找出‘数字游民指南’这个出版物里，所有标题包含‘Notion’的文章。” Claude可以调用“获取文章列表”工具（如果该MCP服务器实现了此功能），筛选后返回给你列表。然后你可以继续：“为其中发布于2023年的每一篇文章的开头，都加上一句‘本文是2023年数字工具系列的一部分，请注意某些信息可能已有更新。’”
虽然目前MCP工具可能还不支持如此复杂的批量、条件性更新（这需要服务器端实现相应的工具函数），但这展示了未来的可能性方向。更现实的当前应用是，你可以让AI帮你生成每周或每月的订阅者增长简报，基于获取到的数据进行分析和总结。
4.3 场景三：协同创作与内容格式化
Substack支持丰富的文章格式，包括嵌入图片、视频、推文、付费墙分割线等。手动编写这些HTML或特定语法很麻烦。MCP工具可以帮你标准化这个过程。
例如，你可以训练Claude：“以后所有文章，在引言后面都自动插入一个居中的、引用格式的‘关键要点’摘要框。” 或者，“帮我把这一长段代码用Substack支持的代码块格式包裹起来，语言设置为Python。”
你甚至可以为不同的内容类型（如采访、书评、新闻快讯）创建标准模板，然后让AI根据模板和你的原始材料快速生成格式规范、可直接发布的草稿。这极大地保证了出版物视觉风格的一致性，也把创作者从重复的格式劳动中解放出来。
5. 安全考量、局限性与进阶配置
5.1 安全风险与最佳实践
使用此类工具，必须将安全放在首位：
- 凭证安全：如前所述，基于Cookie的认证方式风险较高。Cookie一旦泄露，他人即可完全控制你的Substack账户。最佳实践是：
- 使用
.env文件管理凭证，并确保该文件在.gitignore中，绝不提交。 - 定期更新Cookie（因为会话会过期）。
- 考虑是否使用一个专门用于自动发布的“子账户”或“发布者角色”（如果Substack支持），以限制权限。
- 使用
- 代码审计：对于任何需要你输入敏感凭证的开源项目，花点时间粗略阅读其核心源码（特别是处理认证和发起网络请求的部分），确保没有将你的凭证发送到第三方服务器。
- 操作权限：在MCP服务器配置中，理论上可以精细控制暴露哪些工具。如果项目代码支持，你可以在启动时只启用“创建草稿”功能，而禁用“直接发布”或“管理订阅者”功能，实现最小权限原则。
- 客户端安全：确保你使用的AI客户端（如Claude Desktop）是官方正版，并从可信渠道下载。MCP配置是本地存储的，客户端的安全性同样重要。
5.2 当前局限与可能的问题
- API稳定性：由于Substack未提供公开API，该项目是逆向工程其内部接口实现的。这意味着一旦Substack网站更新，接口可能变动，导致工具失效。你需要关注项目的GitHub仓库，及时更新代码。
- 功能覆盖度：可能无法覆盖Substack的所有功能，如评论管理、付费帖子价格设置、邮件模板编辑等。功能是否齐全完全取决于项目维护者的开发进度。
- 错误处理：网络超时、认证失效、内容格式错误等情况的错误信息，可能经过MCP服务器和AI客户端两层转发后，变得对用户不友好，排查问题需要一定的经验。
- 内容质量依赖AI：工具本身不产生内容，它只是桥梁。最终发布内容的质量，高度依赖于你给予AI的指令清晰度和AI本身的能力。垃圾指令只会产生垃圾输出。
5.3 性能优化与自定义扩展
如果你觉得这个工具很好用，但有些功能缺失，可以考虑自行扩展。这需要一定的JavaScript/TypeScript和Node.js知识。
- 添加新工具：在项目的源代码中，工具通常在
src/tools/目录下定义。每个工具是一个符合MCP SDK规范的对象，包含name、description、inputSchema（定义参数）和execute函数。你可以模仿现有工具，编写一个新的，例如添加一个“搜索文章”的工具。 - 改善错误处理：在工具的
execute函数中，增加更细致的try-catch，对不同的Substack API错误返回更清晰的提示，这能极大提升使用体验。 - 添加本地缓存：对于“获取文章列表”这类读多写少的操作，可以引入简单的内存或文件缓存，设定短时间的有效期，以减少对Substack服务器的请求，提升AI助手的响应速度。
- 支持多账户：修改配置结构，使其支持多个Substack账户的凭证，并根据AI指令中的上下文动态切换，适合机构或团队使用。
6. 故障排除与常见问题实录
在实际配置和使用过程中，你几乎一定会遇到一些问题。以下是我踩过坑后总结的排查清单：
| 问题现象 | 可能原因 | 排查步骤与解决方案 |
|---|---|---|
| Claude Desktop 启动后不显示Substack工具 | 1. MCP服务器配置错误。 2. Claude Desktop未正确重启。 3. 服务器启动失败。 | 1. 检查claude_desktop_config.json格式是否正确，路径是否存在空格或中文，建议使用绝对路径。2. 彻底退出Claude Desktop（检查进程是否残留），再重新启动。 3. 在终端手动运行配置中的命令（如 node /path/to/index.js），看服务器能否独立启动并输出日志，根据错误信息修复（通常是缺少依赖或Cookie无效）。 |
| AI调用工具时返回“认证失败”或“无效会话” | 1. Substack会话Cookie已过期。 2. Cookie值复制不完整或有额外字符。 | 1. 重新登录Substack，提取新的Cookie值，更新.env文件或配置。2. 检查复制的Cookie值，确保没有多余的空格或换行符。可以尝试用 echo $SUBSTACK_SESSION_COOKIE命令（Linux/macOS）或在Node脚本中打印出来确认。 |
| 发布文章成功，但格式错乱（代码块不显示等） | AI生成的正文格式与Substack API预期不符。 | 1. Substack的发布接口可能只接受纯HTML或特定的Markdown子集。明确指示AI：“请以纯HTML格式输出文章正文。”或“使用标准的Markdown语法。” 2. 在MCP服务器的代码中，可以添加一个后处理函数，在发送前将AI返回的Markdown统一转换为Substack兼容的HTML。 |
| 工具调用超时或无响应 | 1. 网络问题。 2. MCP服务器进程僵死。 3. Substack API响应慢。 | 1. 检查网络连接。 2. 重启Claude Desktop和MCP服务器进程。 3. 在工具调用中增加超时（timeout）逻辑，并在前端给出友好提示。这需要修改MCP服务器代码。 |
| 无法找到或切换到特定出版物 | 1. 配置的出版物URL或ID错误。 2. 该MCP服务器未实现“列出出版物”工具。 | 1. 确认你在Substack上的出版物主页URL，确保配置正确。 2. 尝试使用出版物的内部ID而非名称或URL。可以通过浏览器开发者工具，在网络请求中查找发布文章时传递的 publication_id参数。3. 如果工具未实现，暂时只能通过配置默认值来操作一个主要出版物。 |
一个关键的调试技巧：始终从终端手动启动你的MCP服务器开始。在项目目录下运行npm start或直接运行node index.js。观察控制台输出，正常情况下它会打印出服务器已启动、暴露的工具列表等信息。当你在Claude中调用工具时，终端会实时打印出收到的请求和发出的响应，这是定位问题最直接的方式。如果手动启动都报错，那么问题肯定出在服务器本身（依赖、配置、代码）；如果手动启动正常但Claude无法连接，问题就出在Claude的配置或两者间的通信上。