1. 项目概述一个让AI帮你写Substack的“智能副驾”最近在折腾AI工作流的朋友可能都听说过MCPModel Context Protocol这个概念。简单来说它就像给AI大模型比如Claude、GPT装上了一套标准化的“手和脚”让它们不仅能和你聊天还能安全、可控地去操作各种外部工具和服务。而我今天要拆解的这个项目dkships/substack-publisher-mcp就是一个非常典型的MCP服务器实现——它的核心功能是让AI助手能够直接帮你发布和管理Substack上的内容。想象一下这个场景你正在和Claude讨论一个技术话题聊着聊着一篇博客的草稿就成型了。在以前你需要手动复制粘贴到Substack的后台设置标题、摘要、封面图选择发布时间和邮件列表……现在你只需要对AI说一句“嘿帮我把刚才聊的这篇发到我的Substack上标题用‘XX技术实战’明天早上8点定时发布。” 剩下的繁琐操作AI就能通过这个MCP服务器替你完成。这不仅仅是自动化更是将内容创作从“编辑-发布”的割裂流程变成了一个无缝衔接的、对话式的自然交互体验。这个项目正是为这种体验提供了底层桥梁。它适合谁呢首先是Substack的深度用户和创作者尤其是那些更新频繁、希望提升效率的内容生产者。其次是AI工作流爱好者、开发者以及任何对“智能体”Agent如何与现实世界服务交互感兴趣的人。通过剖析这个项目我们不仅能学会如何使用这个工具更能深入理解MCP协议的设计哲学、如何安全地授权AI操作第三方API以及在实际部署中可能遇到的种种“坑”。接下来我就结合自己的部署和测试经验带你从里到外彻底搞懂它。2. 核心架构与MCP协议解析2.1 MCP协议AI的“标准化外设接口”要理解这个项目必须先搞懂MCP是什么。你可以把它类比为电脑的USB协议。在USB出现之前每个外设打印机、鼠标都需要自己的专用接口和驱动混乱且麻烦。MCP之于AI模型就如同USB之于电脑它定义了一套标准化的通信协议让不同的AI模型Claude Desktop, Cursor等“主机”能够以一种统一、安全的方式去发现、调用各种外部工具和服务即MCP服务器好比“外设”。这个协议的核心在于“资源”Resources和“工具”Tools两个概念。资源是AI可以读取的东西比如一个文件列表、一篇草稿的内容。工具是AI可以执行的操作比如发布文章、上传图片。MCP服务器负责向AI主机宣告“我这里有哪些资源可以查看有哪些工具可以使用。” AI主机则根据用户的指令选择合适的工具来调用。substack-publisher-mcp服务器就向AI宣告了诸如create_substack_post创建帖子、list_substack_publications列出订阅号等工具。这种设计带来了几个关键优势安全性AI模型本身不持有你的Substack API密钥。密钥保存在你本地运行的MCP服务器环境中AI只是通过安全的进程间通信IPC发送操作请求。这比直接把密钥交给AI要安全得多。标准化无论底层Substack API如何变化只要MCP服务器的接口不变AI侧就不需要做任何调整。这降低了耦合度。可组合性你可以同时运行多个MCP服务器比如一个管Substack一个管GitHub一个管日历AI就能同时拥有操作多个系统的能力成为一个真正的“全能助手”。2.2 项目架构拆解从代码到功能dkships/substack-publisher-mcp这个项目本质上是一个用TypeScript编写的Node.js服务。它基于官方的modelcontextprotocol/sdk开发这个SDK封装了MCP协议底层的通信细节比如SSE或stdio传输让开发者可以专注于实现具体的工具和资源逻辑。项目的核心文件通常是src/index.ts。我们来看看它内部大概是如何组织的以下为逻辑拆解非直接源码// 伪代码逻辑示意 import { Server } from modelcontextprotocol/sdk/server/index.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; // 1. 创建MCP服务器实例 const server new Server( { name: substack-publisher, version: 1.0.0 }, { capabilities: { tools: {}, resources: {} } } ); // 2. 定义工具Tools // 例如创建Substack帖子的工具 server.setRequestHandler(CallToolRequestSchema, async (request) { if (request.params.name create_substack_post) { const { publicationId, title, body, ... } request.params.arguments; // 3. 在这里调用真实的Substack API const response await substackApi.createPost(publicationId, { title, body }); return { content: [{ type: text, text: Post created successfully! ID: ${response.id} }] }; } // ... 处理其他工具 }); // 4. 定义资源Resources比如获取已发布文章列表 server.setRequestHandler(ListResourcesRequestSchema, async () { return { resources: [ { uri: substack://posts/draft, name: Draft Posts }, { uri: substack://posts/published, name: Published Posts } ] }; }); // 5. 启动服务器使用stdio传输方式与AI主机通信 const transport new StdioServerTransport(); await server.connect(transport);从架构上看它清晰地分为了三层协议层由MCP SDK处理负责与AI主机如Claude Desktop建立连接和基础通信。业务逻辑层这是项目的核心实现了list_publications、create_post、upload_image等具体工具的处理函数。每个函数内部都会去调用官方的Substack API。API适配层封装了对Substack API的HTTP调用处理认证使用Bearer Token、参数序列化、错误响应等。这种分层设计使得代码结构清晰未来如果Substack API有变动只需要修改API适配层如果想增加新工具比如“删除文章”或“管理评论”只需在业务逻辑层添加新的处理函数即可。注意MCP服务器默认使用stdio标准输入输出作为传输层这是一种简单、跨进程的通信方式非常适合与本地桌面应用集成。这意味着该服务通常作为后台进程运行通过命令行管道与AI主机交换数据。3. 环境准备与详细配置指南3.1 前置条件与工具链选择在开始之前你需要准备好以下环境这是我实测最顺畅的搭配Node.js 环境版本需在18.x或以上。推荐使用nvmNode Version Manager来管理Node版本这样可以避免全局权限问题。你可以通过node --version检查。代码仓库获取使用git克隆项目到本地。git clone https://github.com/dkships/substack-publisher-mcp.git cd substack-publisher-mcp包管理器项目通常使用npm或yarn。我推荐使用pnpm它在依赖安装速度和磁盘空间占用上更有优势。如果你没有安装可以用npm install -g pnpm来安装。Substack 账户与 API 密钥这是最关键的一步。你需要一个Substack创作者账户并生成API密钥。登录你的Substack后台。进入Settings-API Keys页面如果找不到Substack可能仍在逐步开放此功能请确保你的账户有权限。点击“Generate new key”为其起一个名字例如“MCP-Server”并复制保存好生成的密钥。这个密钥只会显示一次务必妥善保存。3.2 依赖安装与项目初始化进入项目目录后安装依赖# 使用pnpm推荐 pnpm install # 或者使用npm npm install安装过程会拉取modelcontextprotocol/sdk以及其他必要的依赖如axios用于HTTP请求dotenv用于管理环境变量。接下来是配置环节。项目一般会使用环境变量来管理敏感信息。你会在根目录找到一个.env.example或类似的示例文件。# 复制示例文件创建你自己的.env文件 cp .env.example .env然后用你喜欢的文本编辑器打开.env文件填入你的Substack API密钥# .env 文件内容示例 SUBSTACK_API_KEYsk_live_xxxxxxxxxxxxxxxxxxxxxxxx # 替换为你的真实密钥实操心得永远不要将.env文件提交到git仓库确保它在.gitignore列表中。这是保护API密钥最基本、最重要的一步。我习惯在克隆项目后第一时间检查.gitignore文件是否包含了.env。3.3 配置AI客户端以Claude Desktop为例要让Claude Desktop能使用我们这个MCP服务器需要进行配置。Claude Desktop的配置文件通常位于以下路径macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonLinux:~/.config/Claude/claude_desktop_config.json你需要编辑这个JSON文件在mcpServers字段下添加我们的服务器配置。如果该字段不存在就创建它。{ mcpServers: { substack: { command: node, args: [ /ABSOLUTE/PATH/TO/YOUR/substack-publisher-mcp/build/index.js ], env: { SUBSTACK_API_KEY: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx } } } }关键参数解析command: node指定用Node.js运行时来执行我们的服务器脚本。args这里的路径必须是绝对路径指向编译后的JavaScript入口文件。通常项目构建后代码会在build或dist目录下。你需要先运行构建命令如npm run build生成这个文件。env这里可以直接传入环境变量。我强烈建议将API密钥放在这里而不是在.env文件中尤其是当你可能分享项目时。这样配置更安全且与Claude Desktop绑定。配置完成后必须完全重启Claude Desktop应用新的MCP服务器配置才会被加载。4. 核心功能实操与API调用详解4.1 构建、测试与运行服务器在配置客户端之前我们最好先在本地测试一下服务器是否能正常运行。首先构建项目如果项目是TypeScript编写npm run build # 或 pnpm build构建成功后你可以尝试直接运行服务器看是否有错误输出# 假设入口文件是 build/index.js并且.env已配置 node build/index.js如果一切正常你可能看不到太多输出因为MCP服务器通过stdio通信在等待输入或者会看到一些初始化日志。按CtrlC退出。更专业的测试方法是使用MCP协议提供的测试工具例如modelcontextprotocol/sdk自带的工具或其他兼容的MCP客户端进行工具列表查询。不过最直接的测试还是通过配置好的Claude Desktop来进行。4.2 核心工具使用场景与指令示例当Claude Desktop成功连接后你就可以在对话中直接使用相关功能了。以下是一些典型的使用场景和你可以对AI发出的指令场景一列出你的所有Substack订阅号你的指令“查看一下我的Substack里有哪些订阅号publications。”AI背后的操作AI会调用MCP服务器的list_substack_publications工具。服务器收到请求后会向Substack API发送GET /api/v1/publications请求携带你的API密钥获取列表后返回给AIAI再以友好的格式呈现给你。返回示例你目前管理以下订阅号 1. 「科技漫谈」 (ID: pub_abc123) - 主订阅号 2. 「每周随笔」 (ID: pub_def456) - 新闻通讯场景二创建并发布一篇新文章你的指令“帮我在「科技漫谈」这个订阅号下创建一篇新文章。标题是‘深入理解MCP协议’正文内容就是我们刚才讨论的那些要点。把它设为草稿先别发布。”AI背后的操作AI解析你的指令提取出publicationId可能是名称或IDAI会尝试匹配、title、body正文内容。调用create_substack_post工具并传入这些参数。其中body需要符合Substack的富文本格式通常是HTML。MCP服务器会向Substack API发送POST /api/v1/publications/{publication_id}/posts请求。创建成功后AI会返回文章的唯一ID和编辑链接。关键参数详解send布尔值。false表示存为草稿true则立即发布并发送给订阅者。强烈建议先设为false进行测试。body文章正文。Substack支持有限的HTML标签如p,h2,ul,li,a,strong,em。如果你让AI从Markdown格式转换需要确保转换逻辑正确。场景三上传图片并插入文章你的指令“我想在文章里插入一张图表图片文件在我桌面上叫architecture.png。”AI背后的操作AI需要先读取本地图片文件。这可能需要另一个MCP服务器如file服务器或通过其他方式获取图片的base64数据。然后AI调用upload_image_to_substack工具如果项目实现了该工具将图片数据、文件名和对应的publicationId传给MCP服务器。服务器调用Substack的图片上传API返回图片的URL。AI将这个URL以Markdown或HTML格式![架构图](图片URL)插入到文章正文中。场景四管理已有文章你的指令“把我‘科技漫谈’里所有还是草稿状态的文章列出来。” 或 “把ID为12345的那篇文章修改标题并安排到下周五上午10点发布。”AI背后的操作这分别对应list_substack_posts可能带筛选参数和update_substack_post工具。更新文章可能涉及调用PUT /api/v1/posts/{post_id}接口。注意事项在与AI交互时尽量提供明确的信息。例如说“在我的‘主博客’订阅号下发布”不如直接提供订阅号ID或确切的名称。因为AI需要将你的自然语言描述精确映射到工具的参数上。4.3 Substack API调用安全与限流考量项目核心是调用Substack的API。这里有几个重要的实践细节认证方式Substack API目前主要使用Bearer Token认证。即在HTTP请求头中携带Authorization: Bearer YOUR_API_KEY。MCP服务器会在所有出站请求中自动添加这个头。API速率限制Substack对API调用有速率限制。虽然公开文档可能不明确但作为最佳实践你应该在代码中实现简单的请求队列或延迟避免短时间内发起大量请求。尤其是在批量操作时如获取所有文章列表。一个简单的防抖策略是在连续请求间添加100-200ms的间隔。错误处理完善的MCP服务器应该能优雅地处理API错误如401未授权、429请求过多、500服务器错误并将有意义的错误信息通过MCP协议返回给AI再由AI转述给你。例如“Substack API返回了429错误可能是请求太频繁了请稍后再试。”5. 常见问题排查与实战经验分享即使按照步骤操作也难免会遇到问题。下面是我在部署和使用过程中遇到的一些典型问题及解决方法。5.1 连接与配置问题问题1Claude Desktop重启后无法识别Substack工具。现象在Claude中输入指令AI回复说“我不知道如何操作Substack”或没有相关工具列表。排查步骤检查配置文件路径和语法确认claude_desktop_config.json路径正确且JSON格式无误可以使用在线JSON校验工具。一个多余的逗号就会导致整个配置失效。检查服务器路径确认args中的JavaScript文件绝对路径100%正确并且该文件已由npm run build成功生成。查看Claude Desktop日志这是最关键的步骤。在macOS上你可以在终端运行log stream --process Claude来实时查看日志。在Windows上日志可能位于%APPDATA%\Claude\logs。查找包含“MCP”、“substack”或“spawn”关键字的错误信息。常见的错误是ENOENT文件不存在或EACCES权限不足。验证服务器独立运行在终端直接运行node /ABSOLUTE/PATH/TO/index.js看是否有立即报错如缺少模块。这能排除环境变量或依赖问题。问题2API密钥无效错误。现象AI尝试操作时返回“Authentication failed”或“Invalid API key”。解决确认你的Substack账户有生成API密钥的权限。确认API密钥已正确复制没有多余的空格或换行。最好在.env文件或Claude配置中重新粘贴一次。确认你配置的环境变量名与代码中读取的变量名一致通常是SUBSTACK_API_KEY。如果密钥在Claude配置的env中确保重启了Claude Desktop。5.2 功能使用与API问题问题3AI创建的帖子格式错乱。现象发布后的文章段落挤在一起列表没有换行或图片不显示。原因与解决Substack的正文字段期望的是HTML但AI可能输出了Markdown或纯文本。方案A推荐在给AI的指令中明确要求。“请将正文内容转换为简单的HTML格式使用p标签表示段落h2表示二级标题ul和li表示列表。”方案B修改MCP服务器的create_substack_post工具在将内容发送给Substack API之前内置一个从Markdown到简单HTML的转换逻辑例如使用marked库。但这会增加服务器复杂度。问题4上传图片失败。现象AI提示图片上传失败或上传后无法插入。排查首先确认upload_image_to_substack工具是否已在该MCP服务器中实现。不是所有版本都包含此功能。确认图片文件路径可被AI访问。如果AI本身没有文件系统权限则需要通过其他方式如让用户先上传到图床或使用专门的filesystemMCP服务器获取图片数据。查看Substack API对图片格式、大小是否有限制。通常支持常见的PNG、JPG大小可能限制在几MB以内。问题5操作速度慢或超时。现象一个简单的列出版物请求AI很久才响应或超时。解决网络问题检查你的网络连接。Substack API服务器可能在海外。API限流你可能触发了Substack的速率限制。在代码中添加请求间隔。MCP服务器性能如果是第一次启动或服务器代码有性能问题如同步进行大量操作可能导致响应慢。检查服务器代码是否有不必要的阻塞操作。5.3 进阶调试技巧当问题比较复杂时可以启用更详细的日志。在MCP服务器中增加日志修改服务器代码在关键步骤如收到请求、调用API前、收到API响应后使用console.error输出日志。这些日志会打印到运行服务器的终端如果通过Claude启动则需要在Claude的日志中查看。// 在工具处理函数中添加 console.error([DEBUG] Received request to create post for publication: ${publicationId});使用专业的MCP客户端进行测试除了Claude Desktop你可以使用像mcp-cli这样的命令行工具来直接与你的MCP服务器交互测试工具调用这能排除AI层面的干扰。直接测试Substack API使用curl或 Postman 直接调用Substack API验证你的API密钥和请求参数是否正确。这是定位问题最直接的方法。curl -H Authorization: Bearer YOUR_API_KEY https://api.substack.com/api/v1/publications6. 安全最佳实践与扩展思路6.1 安全是重中之重让AI操作你的内容发布平台安全必须放在第一位。最小权限原则在Substack上生成API密钥时如果有关联范围Scope的选项只授予它发布文章和管理帖子所必需的权限不要给予账户管理、财务等无关权限。环境隔离永远不要在公共环境如线上服务器、不可信的容器中运行配置了真实API密钥的MCP服务器除非你完全信任该环境。本地开发是最安全的。密钥管理绝对不要将API密钥硬编码在代码中或提交到版本控制系统。优先使用Claude Desktop配置中的env字段而非项目内的.env文件特别是当你可能与他人共享项目代码时。考虑使用系统的密钥管理工具如macOS的Keychain、Windows的Credential Manager来存储密钥然后在启动服务器时通过脚本读取。但这需要修改服务器启动方式。操作确认对于“发布”或“删除”这类高风险操作一个更安全的设计是让MCP服务器工具返回一个预览或确认请求需要用户显式确认例如在AI对话中回答“是的确认发布”后才执行最终操作。这可以在服务器逻辑中实现一个“两阶段提交”。6.2 功能扩展与自定义这个开源项目是一个很好的起点你可以根据自己的需求进行扩展增加更多工具delete_substack_post删除文章。get_post_analytics获取文章的阅读数、订阅增长等数据。manage_comments审核或回复文章评论。实现这些功能需要研究Substack官方API文档并在服务器中添加对应的工具处理函数。增强内容处理内置Markdown到HTML的转换器让AI只需输出Markdown。添加图片自动优化或压缩逻辑再上传。实现“从URL导入内容”的工具让AI能根据一个链接抓取并格式化内容。与其他服务集成将Substack发布作为更宏大AI工作流的一环。例如你可以搭建一个工作流AI先根据热点生成大纲 - 调用搜索引擎MCP工具收集资料 - 撰写长文 - 调用本服务器发布到Substack - 调用社交媒体MCP工具自动推广。这需要你运行多个MCP服务器并由一个“智能体”协调中心来调度。改进用户体验让工具的参数更智能。例如list_publications工具可以返回更结构化的信息如ID、名称、描述AI可以缓存这些信息后续你只需说“在我的科技博客上发布”AI就能自动匹配到正确的publicationId。这个项目的价值远不止于“一键发布”。它代表了一种未来人机协作的范式AI作为理解你意图的“大脑”而一个个MCP服务器则是执行具体任务的“四肢”。通过深入理解和定制这样的工具你不仅能提升当下Substack创作的效率更是在亲身实践和塑造下一代人机交互的界面。从配置环境时的小心翼翼到第一次成功用一句话发布文章时的畅快感这个过程本身就是对未来工作方式的一次生动预演。