基于MCP协议与Substack官方API构建AI数据分析助手-平芜编程栈

1. 项目概述：一个为AI助手打造的Substack数据工具箱

如果你和我一样，同时运营着几个Substack邮件列表，那你肯定经历过这种场景：想快速查一下上周那篇爆款文章的打开率，或者对比一下两个不同主题的邮件列表在过去一个月的付费订阅增长趋势。通常，你需要登录Substack后台，在几个不同的页面间来回切换，导出CSV，再用Excel或者Google Sheets做数据透视。这个过程不仅繁琐，而且打断了你原本的创作或分析思路。

最近，我在尝试将更多日常工作流交给像Claude、Cursor这类AI助手来辅助完成时，就遇到了这个痛点。我希望AI能直接“看到”我的Substack数据，并基于这些数据帮我分析趋势、总结报告，甚至草拟后续的创作方向。然而，Substack官方并没有为AI助手提供直接的接口。市面上虽然有一些基于非官方API（通常是通过模拟浏览器登录获取Cookie）的MCP工具，但它们非常脆弱，一旦Substack前端改版，工具就失效了，而且通常不支持多邮件列表管理。

这正是substack-publisher-mcp这个项目诞生的背景。它是一个MCP服务器，专门桥接AI助手与Substack官方的Publisher API。简单来说，它就像给你的Claude或Cursor安装了一个“Substack数据插件”。安装配置好后，你可以直接用自然语言向AI提问，比如：“帮我列出主博客过去30天阅读量最高的5篇文章”，或者“对比一下我的科技通讯和公司动态通讯本月的付费订阅转化率”，AI就能调用这个工具，直接从Substack官方API获取实时、准确的数据来回答你。

这个工具的核心价值在于其稳定性和官方性。它使用的是Substack官方发布并维护的Publisher API，这意味着只要官方API不变，工具就能稳定工作。同时，它原生支持多邮件列表（Publication）管理，对于像我这样管理多个垂类内容的创作者来说，简直是效率神器。接下来，我将详细拆解如何从零开始部署和使用这个工具，并分享我在实际配置和日常使用中积累的一些关键技巧和避坑经验。

2. 核心原理与架构解析：MCP如何成为AI的“手和眼”

在深入实操之前，我们有必要花点时间理解一下背后的核心概念：MCP和Publisher API。这能帮助你更好地理解这个工具的能力边界，并在遇到问题时知道该从哪里着手排查。

2.1 Model Context Protocol：AI的“可插拔”能力扩展

MCP，全称Model Context Protocol，你可以把它理解为AI领域的“USB协议”或“驱动标准”。在MCP出现之前，如果你想让人工智能模型（比如Claude）去操作你电脑上的文件、查询数据库或者调用某个网站的API，开发者需要为每一个AI模型和每一个工具（或数据源）单独编写复杂的集成代码，过程冗长且不通用。

MCP定义了一套标准化的通信协议。一方面，MCP服务器（Server）负责封装对特定资源（如本地文件系统、数据库、Substack API）的访问能力，并将其暴露为一系列标准的“工具”。另一方面，MCP客户端（Client），比如Claude Desktop、Cursor IDE，内置了MCP协议支持，可以动态发现、加载并调用这些服务器提供的工具。

substack-publisher-mcp就是一个标准的MCP服务器。它的职责非常专一：与Substack的Publisher API对话，并将API的复杂参数和JSON响应，包装成AI模型能轻易理解和调用的几个简单“工具函数”，例如list_posts、get_subscriber_counts。

为什么这很重要？这意味着作为使用者，你完全不需要教AI怎么去解析Substack的API文档、怎么构造HTTP请求、怎么处理OAuth认证。你只需要告诉AI：“我想看看我的订阅者数据。” AI自己就知道该去调用哪个工具，并理解返回的数据结构。这极大地降低了使用门槛，将技术细节隐藏在后台，让你能专注于数据本身和你的分析目标。

2.2 Substack Publisher API：稳定数据源的基石

与那些通过逆向工程Substack网页端、依赖浏览器Cookie的“野路子”API不同，Publisher API是Substack官方为创作者和开发者提供的正式接口。它的稳定性、数据准确性和长期维护性都有保障。

这个API的核心特点包括：

基于API Key认证：你需要在Substack后台生成一个专用的API密钥。这种方式比维护一个随时可能过期的会话Cookie要稳定和安全得多。
清晰的权限范围：API密钥通常只拥有读取数据的权限（如文章、统计数据、订阅者数量），而无法进行发布、删除等写操作，这符合安全最小权限原则。
结构化的数据响应：所有返回的数据都是格式良好的JSON，包含了明确的字段，如total_email_subscribers（总邮件订阅者）、paid_subscribers（付费订阅者）等，便于程序解析。
原生支持多邮件列表：API的设计本身就考虑到了用户可能管理多个Substack邮件列表，因此在请求中可以通过参数或不同的API密钥来区分数据来源。

substack-publisher-mcp项目所做的，就是为你处理了与这个官方API交互的所有底层细节：HTTP客户端管理、错误处理、请求重试、环境变量读取、多密钥管理等。你只需要提供一个API密钥，它就能为你提供稳定可靠的数据服务。

2.3 工具链选型：Node.js与TypeScript的权衡

这个项目选择Node.js作为运行时，并用TypeScript编写，这是一个非常务实且高效的技术选型。

Node.js：在工具和CLI开发领域，Node.js拥有极其丰富的生态系统。npm包管理器让依赖管理变得轻松，诸如axios（用于HTTP请求）、commander（用于构建命令行接口）、dotenv（用于环境变量管理）等成熟库能快速搭建起项目骨架。同时，Node.js的跨平台特性保证了工具在macOS、Windows和Linux上都能一致运行，这对于需要适配不同用户桌面环境的MCP服务器至关重要。
TypeScript：对于需要与外部API（Substack Publisher API）进行强类型交互的项目，TypeScript提供了巨大的优势。它能在编译阶段就捕获许多潜在的类型错误，比如API响应字段名拼写错误、参数类型不匹配等。这使得代码更加健壮，减少了运行时崩溃的可能。对于开源项目而言，清晰的类型定义也极大地便利了其他贡献者理解和修改代码。

从架构上看，这个项目是一个典型的“胶水层”应用：它不处理复杂的业务逻辑，主要工作是进行协议转换（MCP协议 <-> HTTP API）和数据格式适配。这种架构使得代码保持简洁，未来如果Substack API有更新，通常只需要调整对应的接口模型和请求函数即可，核心的MCP服务器逻辑可以保持不变。

3. 从零开始的完整部署与配置指南

理论部分清晰后，我们进入实战环节。我将以管理两个Substack邮件列表（一个主博客“MainBlog”，一个技术简报“TechDigest”）为例，带你完成从获取API密钥到在Claude Desktop中成功调用的全过程。

3.1 前置准备：获取你的Substack Publisher API密钥

这是整个流程中最关键的一步，且只能在Substack的网页后台完成。

登录Substack：打开 Substack Publisher 并登录你的创作者账户。
进入API设置页面：在后台的侧边栏或设置菜单中，找到“Publisher API”或“API”相关选项。Substack可能会调整界面，如果找不到，可以尝试直接访问https://substack.com/api/keys或在你邮件列表的后台设置中仔细查找“开发者”或“高级”选项。
生成新的API密钥：
- 点击“Create new key”或类似的按钮。
- 系统可能会让你为这个密钥命名，例如“Claude-MCP-Integration”。
- 重要提示：仔细查看权限范围。对于substack-publisher-mcp这个只读工具，通常只需要勾选“Read”相关的权限（如read:posts,read:analytics,read:subscribers）。绝对不要授予不必要的“Write”或“Admin”权限，这是最基本的安全准则。
- 生成后，立即复制并妥善保存这个密钥。它通常只显示一次，形如sk_live_xxxxxx。如果丢失，你需要重新生成。

注意：为每个不同的邮件列表或使用场景创建独立的API密钥是一个好习惯。例如，我可以为“MainBlog”和“TechDigest”分别生成一个密钥。这样，即使其中一个密钥意外泄露，你也可以单独撤销它，而不会影响其他服务。

3.2 项目安装与构建：获取并准备MCP服务器

由于这是一个开源项目，我们需要从GitHub上获取代码并在本地构建。

# 1. 克隆项目仓库到本地 git clone https://github.com/dkships/substack-publisher-mcp.git cd substack-publisher-mcp # 2. 安装项目依赖 # 这里会下载axios、@modelcontextprotocol/sdk等必要的npm包 npm install # 3. 构建项目 # 此命令会将TypeScript源代码编译成JavaScript，输出到 `dist/` 目录 npm run build

实操心得：

确保你的本地环境已安装Node.js 18或更高版本。你可以在终端运行node --version来检查。
如果npm install速度慢，可以考虑配置淘宝镜像：npm config set registry https://registry.npmmirror.com。
npm run build这一步必不可少。MCP客户端最终执行的是dist/index.js这个编译后的文件，而不是src/下的源码。忘记构建是导致“服务器无法启动”的常见原因。

3.3 配置MCP客户端：以Claude Desktop为例

不同的AI客户端配置方式略有不同，但核心逻辑一致：在客户端的配置文件中，声明一个MCP服务器，并指定其启动命令和环境变量。

对于Claude Desktop (macOS)：

找到配置文件路径：~/Library/Application Support/Claude/claude_desktop_config.json
- 注意：~代表你的用户主目录。你可以在终端输入open ~/Library/Application\ Support/Claude快速打开该文件夹。
编辑这个JSON文件。如果文件不存在，就创建一个。
添加substack-publisher-mcp服务器的配置。关键点在于args中的路径必须是dist/index.js的绝对路径。

{ "mcpServers": { "substack": { "command": "node", "args": [ "/Users/你的用户名/Projects/substack-publisher-mcp/dist/index.js" ], "env": { "SUBSTACK_API_KEY_MAINBLOG": "sk_live_你的主博客API密钥", "SUBSTACK_API_KEY_TECHDIGEST": "sk_live_你的技术简报API密钥" } } } }

对于Claude Desktop (Windows)：配置文件路径为%APPDATA%\Claude\claude_desktop_config.json。你可以在文件资源管理器的地址栏直接输入%APPDATA%\Claude来定位。

{ "mcpServers": { "substack": { "command": "node", "args": [ "C:\\Users\\你的用户名\\Projects\\substack-publisher-mcp\\dist\\index.js" ], "env": { "SUBSTACK_API_KEY_MAINBLOG": "sk_live_你的主博客API密钥", "SUBSTACK_API_KEY_TECHDIGEST": "sk_live_你的技术简报API密钥" } } } }

配置详解与注意事项：

"command": "node"：指定使用Node.js来运行我们的服务器脚本。
"args"：传递给Node.js的参数，即我们编译好的入口文件。务必使用绝对路径，相对路径很可能导致Claude Desktop找不到文件。
"env"：这里设置环境变量。我们采用SUBSTACK_API_KEY_<NAME>的格式来配置多个邮件列表。<NAME>（如MAINBLOG）是你自定义的标识符，后续在向AI提问时会用到。
安全警告：这个配置文件包含了你的API密钥。请确保不要将其上传到公开的Git仓库或分享给他人。可以考虑使用环境变量管理工具，但对于Claude Desktop配置，目前通常需要明文写入。

3.4 验证与首次使用

配置完成后，重启Claude Desktop客户端。重启是为了让客户端重新读取配置文件并加载新的MCP服务器。

如何验证是否加载成功？一个简单的方法是直接向Claude提问。你可以尝试一些简单的指令：

“列出我配置了哪些Substack邮件列表。”
“查看我的主博客（MainBlog）最近发布的5篇文章。”
“获取我的技术简报（TechDigest）过去7天的订阅者数量变化。”

如果配置正确，Claude会理解你的请求，并在后台调用相应的工具，然后将获取到的数据以清晰、易读的格式呈现给你。如果遇到错误，Claude通常也会将工具返回的错误信息反馈出来，这有助于我们进行下一步的排查。

4. 核心工具详解与高效使用技巧

substack-publisher-mcp提供了6个核心工具，覆盖了创作者最关心的数据维度。理解每个工具的用途、参数和返回数据，能让你更精准地向AI提问，获取更有价值的洞察。

4.1 内容管理工具：洞察你的文章表现

工具1：list_publications

功能：列出所有通过环境变量配置的邮件列表名称。这是一个很好的健康检查工具，用于确认你的多邮件列表配置是否已被服务器正确识别。
使用场景：“我配置了哪几个Substack邮件列表？” 或者在你忘记自定义的<NAME>时快速查询。

工具2：list_posts

功能：按条件列出已发布的文章。这是使用频率最高的工具之一。
关键参数解析：
- publication：可选。指定邮件列表名称，如"MAINBLOG"。如果不指定，默认使用第一个配置的密钥对应的邮件列表。
- startDate/endDate：可选，ISO 8601格式（如"2024-03-01"）。用于筛选发布日期范围。
- sortBy：可选，默认为"postDate"。可按"postDate"（发布日期）或"title"（标题）排序。
- type：可选。可过滤"only_paid"（仅付费用户可见）或"everyone"（所有人可见）的文章。
- maxResults：可选，默认可能为20或50。限制返回的文章数量，用于快速预览。
使用场景：
- “列出我的主博客上个月所有面向付费用户的文章。”
- “找出我的技术简报在今年第一季度发布的所有文章，按标题排序。”
- “给我看看最近10篇发布的文章标题和发布日期。”

工具3：get_post

功能：通过文章的唯一URL Slug获取单篇文章的详细信息，包括完整标题、副标题、封面图、发布时间、受众设置等。
关键参数：urlSlug（必填）。这就是你文章网址的最后一部分，例如文章https://yourblog.substack.com/p/my-awesome-article的urlSlug就是"my-awesome-article"。
使用场景：当你想深入分析某篇特定文章，或者需要获取其完整信息用于生成报告时。

工具4：get_post_stats

功能：获取单篇文章的互动统计数据，这是衡量内容表现的核心。
关键参数：urlSlug（必填）。
返回数据深度解读：
- opens：邮件打开数。衡量标题和预览文案吸引力的关键指标。
- clicks：链接点击总数。反映文章内容对读者的吸引力和你内链/外链的有效性。
- views：网页浏览量。读者在Substack站内或App中阅读文章的次数。
- recipients：邮件发送总数（即该篇文章的订阅者基数）。
- new_free_subscriptions/new_paid_subscriptions：该篇文章带来的新增免费/付费订阅。这是衡量内容转化能力的黄金指标。
- estimated_revenue_increase：该篇文章带来的预估收入增长（基于新增付费订阅计算）。
使用场景：
- “帮我分析一下‘my-awesome-article’这篇文章的数据表现。”
- “对比过去三篇深度长文和新闻快讯的打开率和转化率有什么差异？”

4.2 订阅者分析工具：把握读者增长脉搏

工具5：get_subscriber_counts

功能：获取按天统计的、细分类型的订阅者数量。这是分析增长趋势和运营活动效果的利器。
关键参数：startDate/endDate（通常必填，以限定查询范围，避免数据量过大）。
返回数据深度解读：
- total_email_subscribers：总邮件订阅者。最宏观的增长指标。
- paid_subscribers：当前付费订阅者数。
- free_trial_subscribers：处于免费试用期的订阅者数。监控此数据可以评估付费墙的吸引力。
- comp_subscribers：获赠的免费订阅者数（Complimentary）。
- gift_subscribers：礼品订阅者数。
- founding_subscribers：创始会员订阅者数（如果开通了此功能）。
高效使用技巧：你可以让AI直接基于这些数据绘制趋势图（如果AI支持图表功能），或进行简单的计算分析。例如：“计算一下我的主博客在过去30天里，付费订阅者的日均净增长是多少？”

工具6：get_subscriber

功能：通过邮箱地址查询单个订阅者的详细信息（如订阅状态、加入日期、付费状态等）。请注意，出于隐私考虑，官方API可能对此接口有严格的权限控制和频率限制。
关键参数：email（必填）。
使用场景：通常用于客户支持或处理特定用户查询，日常数据分析中使用频率较低。

4.3 多邮件列表管理实战

这是该工具的一大亮点。配置了多个API密钥后，你可以在每次提问时，通过publication参数指定目标邮件列表。

操作示例：

提问时直接指定：“查看我的TECHDIGEST邮件列表本周的订阅者数据。”
对比分析：“分别获取MAINBLOG和TECHDIGEST过去一个季度的付费订阅增长曲线，并分析哪个主题的转化效率更高。”
内容策略复盘：“列出MAINBLOG中‘仅付费’文章和TECHDIGEST中‘所有人可见’文章在过去两个月的平均打开率。”

通过灵活组合这些工具和参数，你可以将AI变成一个强大的、懂你业务的Substack数据分析助手，从繁琐的重复性数据查询工作中解放出来。

5. 常见问题排查与进阶调试指南

即使按照步骤操作，也可能会遇到一些问题。下面是我在部署和使用过程中遇到的一些典型情况及解决方法。

5.1 服务器启动与连接故障

问题现象	可能原因与排查步骤
Claude提示“无法连接到MCP服务器”或直接没有反应。	1.路径错误：检查`claude_desktop_config.json`中`args`数组里的路径。确保是`dist/index.js`的绝对路径，并且文件名拼写正确。 2.未构建：确认在项目目录下执行过`npm run build`命令，且`dist/index.js`文件确实存在。 3.Node.js版本：运行`node --version`确认版本 ≥ 18。 4.配置文件格式：使用 JSONLint 等工具验证`claude_desktop_config.json`的JSON格式是否正确，确保没有多余的逗号或引号错误。
启动Claude时，终端（如果从终端启动）或系统日志中出现错误。	1.依赖缺失：尝试在项目目录下删除`node_modules`文件夹和`package-lock.json`文件，然后重新运行`npm install`和`npm run build`。 2.权限问题：确保你对项目目录和Node.js有足够的读写和执行权限。
服务器似乎启动了，但Claude说“没有可用的工具”。	1.环境变量未生效：检查`env`配置是否正确，特别是API密钥的变量名（如`SUBSTACK_API_KEY_MAINBLOG`）是否与代码中读取的命名规则一致。最简单的测试方法是，在配置中只保留一个最基本的`SUBSTACK_API_KEY`变量试试。 2.客户端未重载：修改MCP服务器配置后，必须完全退出并重启Claude Desktop，而不仅仅是关闭聊天窗口。

5.2 API认证与数据获取错误

问题现象	可能原因与排查步骤
Claude返回错误信息，包含`401 Unauthorized`或`403 Forbidden`。	1.API密钥错误：这是最常见的原因。请回到Substack后台，确认复制的密钥无误，且没有多余的空格。 2.密钥权限不足：确认在生成API密钥时，勾选了至少包含`read:posts`和`read:analytics`等读取权限。 3.密钥格式：Substack的API密钥通常以`sk_live_`开头。确保整个字符串都被正确放置在双引号内。
工具调用成功，但返回“No data”或空列表。	1.日期范围问题：检查你指定的`startDate`和`endDate`是否合理，是否在邮件列表的运营时间范围内。 2.邮件列表标识符错误：确认`publication`参数与你配置的环境变量名中的`<NAME>`部分完全一致（大小写敏感）。例如，配置的是`SUBSTACK_API_KEY_MYBLOG`，那么提问时使用的标识符就应该是`MYBLOG`。 3.数据延迟：Substack的统计数据（尤其是订阅者数据）可能存在几个小时的处理延迟，最新一天的数据可能尚未就绪。
查询订阅者详情 (`get_subscriber`) 失败。	1.权限限制：你的API密钥可能没有`read:subscribers`的详细权限，或者该接口对某些订阅计划有限制。 2.频率限制：Publisher API有调用频率限制。如果短时间内进行了大量查询，可能会被暂时限制。建议在工具调用间增加间隔，或批量获取数据时使用分页参数（如果工具支持）。

5.3 进阶调试技巧

如果上述方法都无法解决问题，可以进行更底层的调试：

手动测试API密钥：使用curl或 Postman 等工具直接调用Substack Publisher API，验证密钥本身是否有效。例如：
```
curl -H "Authorization: YOUR_API_KEY_HERE" https://publisher-api.substack.com/api/v1/publications/current
```
（请将YOUR_API_KEY_HERE替换为你的真实密钥，注意API端点路径可能需参考最新文档）。如果这里也返回401错误，那问题肯定出在密钥本身。
查看MCP服务器日志：某些MCP客户端或服务器实现可能会输出日志。对于substack-publisher-mcp，你可以尝试直接运行它来查看输出：
```
cd /path/to/substack-publisher-mcp SUBSTACK_API_KEY=your_key_here node dist/index.js
```
如果服务器启动有错误（如缺少依赖），会在这里打印出来。正常启动后，它会等待来自客户端的标准输入。
检查网络环境：确保你的网络环境可以正常访问publisher-api.substack.com这个域名。某些网络策略可能会阻止此类连接。

5.4 安全与维护建议

密钥轮换：定期（如每半年或一年）在Substack后台生成新的API密钥，并在MCP配置中更新，然后废弃旧的密钥。
最小权限原则：只为MCP工具创建具有只读权限的API密钥。永远不要授予其发布、删除或修改设置的权限。
配置文件安全：将claude_desktop_config.json文件纳入你的隐私保护范围。如果你的电脑会与他人共享，请考虑使用操作系统级的加密卷或隐私文件夹来存放此类包含敏感信息的配置文件。
关注更新：订阅substack-publisher-mcp项目的GitHub仓库，关注其Release和Issue，以便及时获取功能更新或安全补丁。更新时，记得重新执行git pull,npm install,npm run build流程。

通过系统地理解和运用这个工具，你不仅能将Substack数据分析的效率提升一个数量级，更能将AI深度融入你的创作与运营工作流中，让数据洞察真正驱动你的内容决策。