1. 项目概述与核心价值最近在折腾内容创作和自动化流程发现一个痛点很多深度内容我习惯在本地用Markdown写好但最终发布到像Substack这样的Newsletter平台时还得手动复制粘贴、调整格式、上传图片一套流程下来创作的热情都快被消磨光了。直到我发现了这个叫dkships/substack-publisher-mcp的项目它像是一把精准的钥匙直接打开了本地工作流与Substack发布平台之间的通道。简单来说这是一个基于MCPModel Context Protocol协议的工具。你可以把它理解为一个“翻译官”或者“适配器”。它的核心工作是让我能在自己熟悉的代码编辑器比如VS Code、笔记软件甚至是命令行终端里直接通过AI助手例如Claude Desktop、Cursor等来操作我的Substack账户完成文章的创建、更新、发布等一系列动作。我不再需要离开我沉浸的创作环境去反复登录网页后台所有操作都集成在了我日常的工作流中。这解决了什么问题对于像我这样的独立创作者、技术博主或者小团队来说它极大地提升了内容发布的效率和体验。我们往往有一套自己的内容生产管线Pipeline可能是用Obsidian写草稿用Git管理版本用脚本处理图片。substack-publisher-mcp的价值就在于它允许我们将Substack无缝地“插入”到这个管线的末端实现从“写完”到“发布”的自动化一跳。它特别适合那些追求效率、喜欢用代码和工具优化工作流并且主要发布平台是Substack的用户。2. MCP协议与工具设计思路拆解要理解这个工具为什么好用得先搞明白它依赖的MCPModel Context Protocol。这不是某个具体的软件而是一个由Anthropic提出的开放协议。你可以把它想象成USB协议它定义了一套标准让不同的“设备”各种工具、数据源和“主机”AI助手能够互相识别和通信。2.1 为什么是MCP在没有MCP之前如果我们想给AI助手比如Claude增加一个“发布到Substack”的能力通常有两种做法一是等Anthropic官方把这个功能集成到Claude里二是自己写一个复杂的插件但往往绑定在某个特定的客户端上换一个环境就用不了。这两种方式都不够灵活。MCP协议的出现改变了这个局面。它采用客户端-服务器Client-Server架构。在这个项目里服务器Server就是substack-publisher-mcp这个工具本身。它封装了所有与Substack API交互的复杂逻辑比如认证、文章格式转换、HTTP请求发送等并按照MCP协议规定的格式对外暴露出一系列“能力”比如create_post,update_post。客户端Client就是支持MCP协议的AI助手应用比如Claude Desktop。客户端启动时会加载配置好的MCP服务器。当用户在客户端里对AI说“帮我把这篇文章发到Substack”AI就会通过MCP协议去调用服务器提供的create_post这个“能力”。这样做的好处是解耦和标准化。工具开发者只需要专注于实现Substack的功能并包装成标准的MCP服务器。任何支持MCP协议的AI客户端都能立即使用这个功能无需为每个客户端单独开发插件。对于我们用户来说选择也变得非常自由我可以今天用Claude Desktop明天换一个同样支持MCP的新工具我的substack-publisher-mcp服务器依然能正常工作。2.2 工具的核心设计考量基于MCP协议这个工具的设计思路非常清晰身份认证安全优先操作Substack账户是敏感行为所以工具首要解决的是安全认证。它采用了Substack官方支持的API Key方式。你的API Key本地存储在配置文件中工具进程在本地运行密钥不会上传到第三方服务器最大程度保障了账户安全。内容格式无损转换创作者本地写的通常是Markdown但Substack的编辑器有其独特的格式虽然不是完全公开的API格式但有其内部表示。工具需要扮演一个“翻译”角色将标准的Markdown可能包含本地图片链接、代码块、特定扩展语法准确地转换为Substack API能够接受并正确渲染的格式。这是工具是否好用的关键也是开发中的难点。操作覆盖核心场景它没有试图覆盖Substack网页后台的所有功能比如数据分析、用户管理而是聚焦于内容创作者最高频的核心操作创建草稿、更新文章、直接发布、上传图片。这符合“工具”的定位做精做透最关键的功能。易于集成与配置作为一个MCP服务器它必须提供简单明了的配置方式。通常是通过一个JSON配置文件让用户填入Substack的API Key和Publication ID出版物ID。好的工具会提供清晰的文档甚至初始化脚本来引导用户完成配置。注意使用这类第三方工具时务必从官方或可信渠道获取API Key并在Substack账户设置中仔细审查API Key的权限范围遵循最小权限原则通常只授予“写入帖子”的权限即可。3. 核心细节解析与实操要点了解了设计思路我们深入看看实际使用中需要关心的核心细节。这决定了工具是“玩具”还是“生产力”。3.1 环境准备与依赖安装这个项目通常由Python编写这是实现MCP服务器的常见选择因此你的系统需要具备Python环境建议3.8以上版本。第一步是获取工具代码。通常通过Git克隆仓库是最佳实践这便于后续更新。git clone https://github.com/dkships/substack-publisher-mcp.git cd substack-publisher-mcp接下来是安装依赖。一个规范的项目会提供requirements.txt或pyproject.toml文件。# 使用pip安装依赖 pip install -r requirements.txt # 或者如果项目使用poetry现代Python项目管理工具 poetry install这里可能会遇到第一个坑依赖冲突。特别是如果你的系统已经安装了很多Python包。建议的最佳实践是使用虚拟环境Virtual Environment将项目的依赖隔离起来。# 创建虚拟环境 python -m venv venv # 激活虚拟环境Linux/macOS source venv/bin/activate # 激活虚拟环境Windows venv\Scripts\activate # 然后在激活的虚拟环境中安装依赖 pip install -r requirements.txt使用虚拟环境可以避免“它能跑但我别的项目炸了”的尴尬局面是Python项目管理的必备习惯。3.2 Substack API Key的获取与配置这是整个工具运行的“钥匙”步骤需要仔细操作。登录Substack打开Substack官网进入你的出版物Publication后台。找到API设置在设置Settings中寻找“开发者”Developers或“API”相关选项。Substack的界面可能会更新如果找不到可以直接在设置页面的搜索框输入“API”。创建API Key点击创建新的API Key。系统可能会让你为这个Key命名比如“Local MCP Tool”。最关键的一步是权限选择。对于发布文章理论上只需要write或posts相关的写入权限。请仔细阅读权限描述只勾选必要的权限例如“创建和更新帖子”。绝对不要直接赋予“完全控制”或所有权限这是安全实践的基本原则。复制并保存Key生成后系统会显示一次API Key字符串。这个字符串只显示一次务必立即将其安全地复制保存下来。你可以将其粘贴到一个临时的文本文件或者直接放入下一步的配置中。关闭页面后你将无法再次查看完整Key只能重新生成。获取到Key后需要配置到substack-publisher-mcp工具中。通常工具会需要一个配置文件比如config.json或settings.toml也可能通过环境变量读取。你需要查阅项目的README文档。一个典型的配置结构可能是{ substack: { api_key: sk_your_actual_api_key_here, publication_id: your_publication_id } }这里的publication_id是你的Substack出版物的唯一标识通常可以在你出版物的主页URL中找到或者在你的后台设置里。实操心得我习惯将API Key存储在系统的密码管理器或使用环境变量而不是硬编码在配置文件中。例如在启动脚本前设置export SUBSTACK_API_KEYyour_key然后在工具的配置代码中读取这个环境变量。这样即使配置文件不小心上传到了GitHub也不会泄露密钥。3.3 与AI客户端的集成配置工具MCP服务器准备好了还需要把它“告诉”你的AI客户端MCP客户端。以目前最流行的Claude Desktop为例。Claude Desktop的MCP服务器配置通常位于一个特定的配置文件中。在macOS上路径可能是~/Library/Application Support/Claude/claude_desktop_config.json。在Windows上可能在%APPDATA%\Claude\claude_desktop_config.json。你需要编辑这个文件在mcpServers字段下添加substack-publisher-mcp服务器的配置。配置需要指定服务器的启动命令和参数。{ mcpServers: { substack-publisher: { command: /path/to/your/venv/bin/python, args: [ /path/to/substack-publisher-mcp/server.py ], env: { SUBSTACK_API_KEY: sk_your_actual_api_key_here, SUBSTACK_PUBLICATION_ID: your_publication_id } } } }关键点解析command这里指向的是你虚拟环境中的Python解释器路径而不是系统全局的Python。这确保了服务器运行在你为该项目安装的依赖环境中。你可以通过which python在激活的虚拟环境中命令来获取这个路径。args指向你克隆的仓库中主服务器脚本文件通常是server.py或main.py。env这里通过环境变量传递敏感信息比在配置文件中硬编码更安全。你也可以将API Key放在这里。配置完成后必须重启Claude Desktop客户端它才会读取新的配置并加载这个MCP服务器。4. 实操过程与核心环节实现配置妥当后激动人心的实操部分就开始了。我们来看如何通过AI助手行云流水般地完成一篇文章的发布。4.1 启动与连接测试重启Claude Desktop后最直接的方式是新建一个对话然后问Claude“你现在有哪些可用的工具或能力” 或者 “你能帮我做什么”。一个正确加载了MCP服务器的Claude通常会回复它现在可以调用哪些工具你应该能在列表中看到与Substack相关的功能比如“create_substack_post”创建Substack帖子。如果没看到说明配置可能有问题。你需要检查Claude Desktop的配置JSON格式是否正确没有语法错误。指定的Python路径和服务器脚本路径是否绝对正确。虚拟环境是否已激活且所有依赖已安装可以手动运行一下python /path/to/server.py看看是否报错。查看Claude Desktop的日志文件通常配置文件夹内里面常有加载MCP服务器失败的详细错误信息。4.2 从本地Markdown到Substack文章假设我本地有一篇写好的Markdown文件my_article.md。现在我可以在Claude的对话窗口中直接将文件内容粘贴进去或者更优雅地告诉Claude文件路径如果Claude有文件读取权限然后发出指令“请使用Substack发布工具将以下内容创建为一篇新的草稿标题是‘深入理解MCP协议如何提升创作效率’。”接下来Claude作为MCP客户端会做几件事解析指令识别出用户意图是“创建Substack帖子”。准备参数它会将文章内容Markdown格式和标题按照substack-publisher-mcp服务器定义的接口格式进行组装。调用工具通过MCP协议向本地运行的substack-publisher-mcp服务器发送一个请求请求执行create_post操作并附上内容和标题。执行与反馈服务器收到请求后使用配置的API Key向Substack官方API发起认证的HTTP POST请求。将Markdown内容转换为Substack API接受的格式这里涉及核心的格式转换逻辑。将标题、内容等参数发送到Substack。接收Substack API的响应通常包含新创建文章的ID、预览链接等。将响应结果格式化后通过MCP协议返回给Claude。结果展示Claude将服务器返回的结果解读并展示给你“成功已在你的Substack‘XXX’中创建了一篇草稿文章ID是12345你可以通过此链接预览https://your.substack.com/p/draft-12345”。这个过程的核心挑战在于第4步的“格式转换”。Substack的编辑器虽然支持Markdown粘贴但其底层API和富文本编辑器有自己的一套HTML和数据结构。一个健壮的工具需要处理好图片处理本地Markdown中的图片链接![](./images/my-chart.png)是相对路径Substack无法识别。工具需要实现自动上传功能读取本地图片文件调用Substack的图片上传接口获取在线URL并替换原文中的链接。这是极大提升体验的功能点。代码块确保代码块的语言标识和缩进被正确保留和渲染。特殊元素如脚注、表格、任务列表等扩展Markdown语法需要测试其兼容性。元数据有些作者习惯在Markdown头部用YAML存储title、subtitle、tags等信息工具最好能解析并利用这些信息。4.3 更新与管理已有文章除了创建更新同样重要。当你需要修改已发布的文章或草稿时你可以对Claude说 “找到我之前发布的标题包含‘MCP协议’的文章将其中的‘第一章’部分更新为以下新内容...” 或者更精确地 “使用Substack工具更新文章ID为12345的文章将正文替换为以下新内容。”这时Claude会调用工具的update_post功能。服务器需要文章的唯一标识ID或Slug和新内容。这里的一个细节是更新操作是覆盖式还是合并式好的工具设计应该允许用户指定更新模式或者至少明确文档说明是覆盖整个文章内容还是可以传递一个“差异”或“部分更新”的指令。通常Substack API的更新端点是覆盖式的所以如果你只想改一段需要先获取原文在本地合并修改再整体提交更新。4.4 直接发布与定时发布创建草稿后你可能想直接发布。指令可以是“将刚才创建的草稿ID 12345立即发布。” 这对应工具的publish_post功能。更进阶的需求是定时发布。Substack API可能支持设置publish_at参数。那么工具是否可以暴露一个schedule_post的能力允许在创建或更新时指定一个未来的时间戳这取决于工具的开发程度和Substack API本身的限制。如果有这个功能那将彻底实现从写作到定时发布的完全自动化流水线。5. 常见问题与排查技巧实录在实际使用中你肯定会遇到各种问题。下面是我在探索过程中遇到的一些典型情况及解决方法希望能帮你避坑。5.1 连接与认证失败问题现象Claude无法调用Substack工具或调用后返回“认证失败”、“无法连接到Substack”等错误。排查思路检查API Key这是最常见的问题。确认Key没有复制错前后有无空格是否已在Substack后台正确创建并启用。可以尝试在命令行用curl命令测试Key是否有效curl -H Authorization: Bearer YOUR_API_KEY https://api.substack.com/v1/publications/YOUR_PUB_ID/posts如果返回401错误就是Key有问题。检查Publication ID确认你使用的出版物ID是否正确并且该API Key有权限操作这个出版物。检查网络环境确保你的网络可以正常访问Substack的API域名api.substack.com。有些网络环境可能有特殊限制。查看工具日志如果工具在运行时有输出日志可能需要在启动命令中增加调试参数或者查看Claude Desktop的MCP服务器日志仔细阅读错误信息。可能是Python依赖缺失如requests库也可能是API的端点URL发生了变化。5.2 内容格式错乱或图片丢失问题现象文章成功创建但Substack上查看时格式乱七八糟代码块没高亮图片显示为破碎图标。解决方案简化初始测试先用一段极其简单的Markdown只有标题、段落和加粗测试确认基础功能正常。再逐步添加复杂元素代码块、图片、表格。图片路径问题如果工具声称支持图片上传确保你传递给它的Markdown内容中图片的路径是服务器进程可以访问的绝对路径。因为MCP服务器是一个独立的进程它不一定能理解Claude对话中提到的“当前目录”或相对路径。最佳实践是在指令中明确提供图片的完整路径或者工具设计为接受文件Base64编码的数据。审查转换逻辑如果问题持续可能需要查看substack-publisher-mcp项目的源码中关于Markdown转换的部分。它可能使用了某个库如markdown、mistune将Markdown转为HTML然后这个HTML需要满足Substack的要求。有时需要自定义一些转换规则。你可以尝试在项目的Issue页面搜索类似问题或者自己动手调试。5.3 AI助手不理解指令或调用错误工具问题现象你对Claude发出了明确的指令但它没有调用Substack工具而是尝试自己去“写”一段发布文章的代码或者调用了其他不相关的工具。排查与解决指令清晰度AI对指令的理解有时需要更精确。尝试使用更直接、与工具功能描述匹配的动词。例如不说“发到Substack”而说“使用Substack发布工具创建一篇帖子”。在指令中明确提及工具名。上下文管理在同一个对话中首次成功调用某个工具后AI在后续对话中会更倾向于使用它。如果开启新对话后失效可能是配置加载问题。客户端兼容性确保你使用的Claude Desktop版本支持MCP。早期版本可能不支持或支持不完善。前往官网更新到最新版。工具描述MCP服务器在启动时会向客户端发送一个“工具清单”其中包含每个工具的名称和描述。检查substack-publisher-mcp的工具描述是否清晰如“Creates a new draft post on Substack”。如果描述太模糊AI可能无法准确匹配。这需要工具开发者优化。5.4 性能与稳定性考量问题发布长文章或多张图片时速度慢或偶尔超时失败。心得分步操作对于超长的文章可以考虑先创建空草稿获取ID然后分段更新。虽然麻烦但比一次性发送大量内容失败要稳妥。图片压缩与CDN如果文章图片很多很大工具在上传时可能会超时。建议在本地先对图片进行压缩使用工具如TinyPNG、ImageOptim。更专业的做法是将图片先上传至图床如Cloudinary、Imgur或CDN在Markdown中直接使用网络URL这样可以绕过Substack的上传步骤极大提升速度和成功率。错误重试机制网络请求难免失败。一个成熟的工具应该内置简单的重试逻辑比如3次重试指数退避。如果当前工具没有对于关键文章手动重试是必要的。你也可以考虑自己fork项目添加这个逻辑。6. 扩展应用与高阶玩法基础发布功能稳定后可以探索更自动化的玩法将substack-publisher-mcp嵌入到更大的工作流中。6.1 与Git和CI/CD集成如果你的文章是用Git管理的强烈推荐便于版本控制和协作你可以创建一个Git钩子Git Hook。例如在post-commit钩子中写一个脚本检测提交的Markdown文件然后自动调用substack-publisher-mcp可以通过其命令行接口如果提供的话来更新对应的Substack草稿。这样每次你本地修改并提交文章对应的线上草稿就自动同步了。更进一步结合GitHub Actions或GitLab CI你可以实现当向Git仓库的main分支推送一个带特定标签如publish的提交时CI流水线自动执行将最新的Markdown内容发布到Substack或更新已发布的文章。这就实现了“基础设施即代码”IaC风格的内容部署。6.2 构建多平台发布管道substack-publisher-mcp解决了Substack的发布问题。但很多创作者是“全平台发布”同样的内容还需要发到个人博客、Medium、知乎等。这时你可以以MCP为核心构建一个发布中台。思路是编写一个“发布调度器”MCP服务器或者一个本地脚本。这个调度器的功能是接收一篇Markdown然后根据配置同时调用多个下游的MCP服务器调用substack-publisher-mcp发布到Substack。调用另一个wordpress-publisher-mcp假设有发布到WordPress。调用devto-publisher-mcp发布到Dev.to。调用一个本地脚本生成静态页面部署到自己的博客。然后你只需要对AI助手说一句“将这篇文章同步到我所有的平台。” 剩下的事情就全部自动化了。MCP的标准化协议使得这种“组合式”工具链成为可能。6.3 内容预处理与增强在内容到达substack-publisher-mcp之前你可以插入一个“预处理”环节。例如自动摘要生成用AI为长文生成摘要并作为文章的副标题或摘要字段提交。关键词与标签提取自动分析文章内容提取关键词并作为Substack的标签Tags提交。格式统一与检查自动检查Markdown语法统一标题样式确保所有图片都有Alt文本利于SEO和无障碍访问。链接预览生成自动抓取文中引用的外部链接生成预览摘要并插入到文章末尾作为“参考阅读”。这些预处理步骤可以通过串联多个AI工具一个负责摘要一个负责检查或者编写一个专门的预处理MCP服务器来实现。最终你将拥有一个高度定制化、智能化的个人内容发布工厂。7. 安全实践与风险规避使用第三方工具连接你的内容平台账户安全永远是第一位的。API Key权限最小化如前所述在Substack后台创建API Key时只授予最必要的权限通常是“帖子”相关的写入权限。不要授予读取用户信息、财务数据或删除数据的权限。隔离使用环境为这类自动化工具单独创建一个Substack子账户如果支持或者至少使用一个专用的API Key而不是你的主账户密钥。这样即使密钥意外泄露影响范围也有限。机密信息管理永远不要将API Key提交到Git仓库中即使是私有仓库。使用环境变量或本地配置文件并通过.gitignore文件确保配置文件不被提交。考虑使用像dotenv这样的库来管理环境变量。定期轮换密钥像管理密码一样定期如每季度在Substack后台撤销旧的API Key生成新的并更新你的本地配置。这可以降低长期暴露带来的风险。审计日志定期查看Substack后台的访问日志或活动日志如果有检查是否有来自异常IP或未知客户端的API调用。这能帮你及时发现潜在的非授权访问。理解工具源码如果可能花点时间阅读substack-publisher-mcp的源代码。重点关注它如何处理你的API Key、向哪里发送网络请求、发送了哪些数据。一个信誉良好的开源项目其代码应该是清晰、透明且没有向第三方服务器发送敏感信息的。如果你不懂代码至少查看项目是否活跃作者信誉如何Issue和Pull Request是否被积极处理。自动化带来了巨大的便利但也增加了攻击面。遵循上述安全实践你就能在享受效率提升的同时将风险控制在可接受的范围内。这个工具代表的是一种趋势未来的创作工具将越来越模块化、协议化通过像MCP这样的开放标准我们可以像搭积木一样自由组合出最适合自己的、强大而个性化的数字工作流。