基于MCP协议与Substack官方API构建AI数据助手

1. 项目概述用AI助手深度管理你的Substack内容生态如果你和我一样同时运营着几个Substack新闻通讯那你肯定对那种在多个后台、数据仪表盘之间来回切换的繁琐感深有体会。查看最新的文章阅读量、追踪付费订阅者的增长趋势、对比不同栏目的表现……这些日常的数据洞察工作虽然重要却常常打断我们专注于内容创作的“心流”。过去我尝试过用脚本抓取数据也试过一些第三方仪表盘工具但它们要么不够灵活要么无法与我的日常工作流无缝集成。最近随着AI助手如Claude、Cursor通过MCP协议获得越来越强的“动手能力”一个想法在我脑中成型能不能让AI助手直接“看到”并“操作”我的Substack后台数据这样我就可以用最自然的语言提问比如“帮我看看上周那篇关于AI趋势的文章表现如何”或者“对比一下我的科技和商业两个通讯过去30天的订阅增长”然后立刻得到结构化的答案甚至让AI基于这些数据给出内容建议。这正是substack-publisher-mcp这个项目要解决的问题。它是一个基于Substack官方Publisher API的MCP服务器。简单来说它就像一座桥梁一端连接着Substack官方、稳定且功能强大的数据接口另一端则连接着支持MCP协议的各类AI工作台。通过这座桥你的AI助手就获得了查询和管理Substack内容的“超能力”。这个工具的核心价值在于其官方性与稳定性。市面上早有一些通过逆向工程Substack内部接口来实现类似功能的工具或脚本但它们有一个致命弱点一旦Substack更新其网站前端或内部API这些“脆弱”的工具就会立刻失效需要开发者不断地“打补丁”。而substack-publisher-mcp直接使用Substack官方为合作伙伴和开发者提供的Publisher API这是一个有正式文档、有版本管理、承诺向后兼容的接口。选择它意味着你构建的自动化工作流不会在某个清晨突然崩溃。它非常适合以下几类人多产的内容创作者需要频繁、快速地查看多篇文章、多个栏目的表现数据以指导后续的创作方向。数据驱动的运营者希望将Substack的订阅者数据、文章互动数据与其他业务数据如网站流量、社交媒体指标进行关联分析。效率至上的极客热衷于用最先进的工具AI助手优化每一个工作环节追求“动动嘴皮子就能获取信息”的流畅体验。管理多个Substack出版物的团队需要统一、便捷地查看旗下所有通讯的运营健康状况。接下来我将带你从零开始完整地部署、配置并使用这个工具并分享我在实际使用中摸索出的技巧和避开的那些“坑”。2. 核心原理与架构设计解析在深入动手之前理解substack-publisher-mcp是如何工作的能帮助你在遇到问题时更快地定位和解决。它的架构可以清晰地分为三层数据源层、桥接服务层和客户端应用层。2.1 数据源层Substack Publisher API这是整个体系的基石。Substack Publisher API是Substack官方提供的、面向出版者的数据接口。与那些通过模拟浏览器登录、抓取HTML页面数据的“野路子”不同这是一个标准的RESTful API。认证方式使用API密钥。你可以在Substack的后台设置中生成一个专有的密钥这个密钥代表了你的身份用于所有API请求的鉴权。它的优点是稳定、安全且可以随时吊销不会危及你的主账户密码。数据范围目前API主要提供读取操作这正是我们进行数据分析最需要的部分。它包括出版物信息获取你管理的Substack出版物列表。文章数据获取已发布文章的列表、详情标题、摘要、发布时间、封面图、受众范围等。文章统计获取单篇文章的深度互动数据如打开数、点击量、阅读量以及最重要的——由这篇文章带来的新免费订阅、新付费订阅和预估收入增长。订阅者数据获取按日统计的订阅者数量细分总邮件订阅者、付费订阅者、免费试用者等以及通过邮箱查询特定订阅者信息。稳定性承诺作为官方APISubstack会尽力保证其向后兼容性。这意味着你今天写的查询代码明年大概率还能正常运行省去了大量维护成本。2.2 桥接服务层MCP服务器这是项目的核心即substack-publisher-mcp本身。它的角色是一个协议转换器和工具暴露器。协议转换MCP模型上下文协议是Anthropic提出的一套标准用于让AI模型安全、结构化地使用外部工具和资源。MCP服务器需要遵循特定的JSON-RPC规范进行通信。substack-publisher-mcp的工作就是接收来自AI客户端的、符合MCP格式的请求例如“调用list_posts工具”然后将这个请求“翻译”成对Substack Publisher API的HTTPS调用携带API密钥请求正确的端点。工具暴露它不仅仅转发请求还以“工具”的形式向AI客户端描述自己的能力。它会告诉Claude或Cursor“嗨我这里有以下几个工具可用list_publications列出出版物、get_post_stats获取文章统计……” 每个工具都有明确的名称、描述和参数定义。这样AI在思考如何回答你的问题时就能知道可以调用哪些工具来获取必要的信息。环境管理与多出版物支持服务器会读取启动时配置的环境变量如SUBSTACK_API_KEY或SUBSTACK_API_KEY_TECH每个环境变量对应一个Substack出版物的API密钥。它负责在内部管理这些密钥与出版物名称的映射关系。当AI客户端的请求指定了publication参数时服务器就能准确地使用对应的密钥去请求数据。2.3 客户端应用层你的AI工作台这是你直接交互的界面通常是Claude Desktop、Claude Code插件或Cursor编辑器。这些应用内置或通过配置支持MCP客户端功能。集成过程你需要在客户端的配置文件中告诉它如何启动我们的MCP服务器即substack-publisher-mcp包括Node.js命令路径、脚本位置以及最重要的环境变量API密钥。协作模式配置成功后当你向AI提问时AI会先理解你的意图。如果发现需要Substack数据它就会查阅已连接的MCP服务器提供的“工具清单”选择合适的工具生成一个结构化的调用请求通过MCP协议发送给服务器。服务器获取数据后返回AI再将这些原始数据整合、分析并用你能理解的自然语言呈现出来。整个流程可以概括为你的自然语言问题 - AI理解并规划 - AI通过MCP调用工具 - 工具服务器访问官方API - 原始数据返回 - AI加工并回答。这个设计巧妙地将AI的语言理解能力与稳定、官方的数据接口结合了起来。3. 从零开始的完整部署与配置指南理论清晰后我们进入实战环节。我会假设你从一个全新的环境开始详细演示每一步。3.1 前期准备获取核心钥匙部署前你需要准备好两样东西Node.js运行环境和Substack的API密钥。1. 安装Node.js 18或更高版本这是运行该MCP服务器的前提。如果你不确定是否安装打开终端Mac/Linux或命令提示符/PowerShellWindows输入node --version如果显示版本号大于等于18则跳过此步。否则请访问 Node.js官网 下载并安装最新的LTS版本。我推荐使用LTS版它在稳定性和兼容性上更有保障。2. 获取Substack Publisher API密钥这是访问你数据的通行证务必妥善保管。步骤一登录你的Substack创作者后台。步骤二在左侧导航栏找到并点击“设置”。步骤三在设置页面中寻找名为“开发者”或“API”的选项卡。Substack的界面可能会更新如果没找到可以尝试在设置页面的搜索框输入“API”或“Developer”。步骤四在API设置部分你应该能看到“Publisher API”的相关选项。点击生成新的API密钥。系统可能会让你确认密码。步骤五重要生成的密钥通常是一长串由数字和字母组成的字符串。请立即将其复制并保存到安全的地方如密码管理器。这个密钥只会显示一次关闭页面后就无法再次查看如果丢失只能重新生成。注意这个API密钥拥有读取你账户下出版物数据的权限。请像保护你的密码一样保护它不要将其提交到公开的代码仓库或分享给他人。3.2 部署MCP服务器有了密钥我们就可以部署桥接服务了。1. 克隆项目代码打开终端切换到你希望存放项目的目录例如~/projects执行以下命令git clone https://github.com/dkships/substack-publisher-mcp.git cd substack-publisher-mcp这会将项目的最新代码下载到本地。2. 安装依赖并构建项目使用TypeScript编写需要安装依赖并编译成JavaScript才能运行。npm install npm run buildnpm install会下载所有必要的第三方库。npm run build则会执行TypeScript编译将src/目录下的源代码编译到dist/目录。请确保build步骤成功完成因为后续MCP客户端启动的是dist/index.js文件。3. 验证安装可选但推荐你可以快速测试一下服务器是否能正常启动。在项目根目录下临时设置环境变量并运行SUBSTACK_API_KEY你的测试API密钥 node dist/index.js如果服务器启动后没有立即退出并报错而是保持运行可能等待连接说明基础运行环境是没问题的。按CtrlC退出测试。3.3 配置你的AI客户端这是最关键的一步让AI助手知道我们的服务器在哪里。配置方式因客户端而异。通用配置结构无论哪种客户端核心配置都是一个JSON对象它定义了如何启动MCP服务器。以下是一个基础模板{ mcpServers: { substack: { command: node, args: [/绝对/路径/到/substack-publisher-mcp/dist/index.js], env: { SUBSTACK_API_KEY: 你刚才获取的真实API密钥 } } } }substack这是你给这个服务器起的名字可以自定义后续AI调用时会用到这个名字或根据上下文自动识别。command启动服务器的命令这里是node。args传递给命令的参数即我们编译好的入口文件index.js的绝对路径。请务必替换成你电脑上的实际路径。env环境变量对象。这里设置SUBSTACK_API_KEY其值就是你的密钥。各客户端具体配置路径与方法Claude Desktop (macOS): 配置文件位于~/Library/Application Support/Claude/claude_desktop_config.json。 如果文件不存在就创建它。将上面的配置模板内容写入该文件即可。Claude Desktop (Windows): 配置文件位于%APPDATA%\Claude\claude_desktop_config.json通常在C:\Users\你的用户名\AppData\Roaming\Claude\。 同样不存在则创建。Claude Code (VS Code 插件): 在你的项目根目录下或者在你的用户全局设置中创建一个名为.mcp.json的文件。配置内容需要稍作调整增加type: stdio{ mcpServers: { substack: { command: node, args: [/绝对/路径/到/substack-publisher-mcp/dist/index.js], env: { SUBSTACK_API_KEY: 你的API密钥 }, type: stdio } } }type: stdio是Claude Code要求的指明使用标准输入输出进行通信。Cursor 编辑器: 在项目根目录下创建.cursor/mcp.json文件注意.cursor是一个目录。其配置格式与Claude Desktop类似无需type字段。配置多出版物支持如果你管理多个Substack比如一个主博客、一个科技简报可以配置多个环境变量。服务器会自动识别以SUBSTACK_API_KEY_为前缀的变量。{ mcpServers: { substack: { command: node, args: [/path/to/dist/index.js], env: { SUBSTACK_API_KEY_MAIN: 主博客密钥, SUBSTACK_API_KEY_TECH: 科技简报密钥 // 注意不需要配置不存在的出版物密钥 } } } }配置完成后重启你的AI客户端Claude Desktop或Cursor以使新的MCP配置生效。4. 核心工具详解与高效使用技巧服务器配置好后AI助手就获得了六把“瑞士军刀”。我们来逐一剖析每把刀的用途、用法以及我摸索出的高效技巧。4.1 工具全景图与基础查询首先你可以让AI帮你列出所有可用的工具。简单地询问“你能用Substack工具做什么”或者“列出可用的Substack相关功能”。AI会调用MCP的list_tools这是一个MCP标准调用非本项目提供或直接展示它已知的来自我们服务器的工具。通常你会看到以下六个工具工具名称核心功能必填参数可选参数与技巧list_publications列出所有已配置的出版物无无。用于确认配置是否正确以及查看出版物在系统中的标识名。list_posts列出符合条件的文章无startDate/endDate(ISO格式如2024-03-01),sortBy(postDate或title),type(all,only_paid,only_free),maxResults(默认20可调大),next(用于分页)。技巧初始查询可不设日期范围快速查看最新文章。get_post获取单篇文章详情urlSlug(文章URL的最后一段)无。urlSlug就是文章发布后其URL中/p/后面的部分。get_post_stats获取单篇文章的互动统计数据urlSlug无。这是分析文章表现的核心工具。get_subscriber_counts获取每日订阅者数量统计无startDate,endDate。强烈建议始终指定日期范围避免获取过量数据。get_subscriber通过邮箱查找订阅者详情email无。适用于核实特定订阅者状态或信息。所有工具都支持一个通用的可选参数publication。当你有多个出版物时用这个参数指定查询目标例如{publication: TECH}。如果不指定服务器通常会使用默认的第一个配置的密钥对应的出版物。4.2 实战场景与高效提问模板知道了工具有哪些关键在于如何组合使用它们。下面是我常用的几个场景和提问方式能极大提升效率。场景一快速健康检查提问“给我的Substack出版物做个快速健康检查看看最近一周的整体订阅趋势和文章表现。”AI背后的行动调用list_publications确认出版物名称。调用get_subscriber_counts设置startDate为7天前获取订阅趋势。调用list_posts设置startDate为7天前maxResults为10获取近期文章列表。对于列表中的每篇文章可能并行调用get_post_stats获取其数据。综合分析数据订阅是增长还是下降哪篇文章打开率最高哪篇带来了最多付费转化最后给你一个简洁的总结报告。场景二深度分析单篇文章提问“深度分析一下我上周发布的题为‘AI写作指南’的那篇文章包括它的基本数据、互动表现以及和之前同类型文章的比较。”AI背后的行动调用list_posts查找标题包含“AI写作指南”的文章获取其urlSlug。调用get_post获取文章详情发布时间、受众等。调用get_post_stats获取该文章的详细统计数据。如果需要比较再次调用list_posts用type或时间范围筛选出同类型历史文章然后批量获取它们的get_post_stats进行对比分析计算平均打开率、转化率等。场景三多出版物对比提问“对比一下我的‘主博客’和‘科技周报’这两个出版物在过去30天的新增付费订阅者数量。”AI背后的行动调用get_subscriber_counts分别指定publication为MAIN和TECH时间范围均为过去30天。从返回的每日数据中提取出new_paid_subscriptions的字段注意这个数据更可能来自get_post_stats的汇总或需要从订阅者计数差值计算。实际中get_subscriber_counts提供的是存量增量需自行计算。AI可能会解释这一点并转而分析付费订阅者总数的变化趋势。这体现了AI的逻辑推理能力——它知道如何解读和运算数据。场景四寻找最佳发布时间提问“分析我过去三个月所有文章的数据找出打开率最高的发布时间是星期几和哪个时间段。”AI背后的行动调用list_posts设置startDate为三个月前maxResults设为50或更大。对每篇文章调用get_post获取精确的postDate。对每篇文章调用get_post_stats获取opens和recipients计算打开率。将所有文章的发布时间星期几、小时与打开率进行关联分析给出统计结论和建议。我的心得不要只问“我的数据怎么样”要问“基于我的数据我应该……”。将AI从“数据检索器”提升为“分析顾问”。例如问“根据最近一个月付费文章和免费文章的表现差异对我接下来的内容策略有什么建议”AI会调用数据并结合常见的新闻通讯运营知识给你更具洞察力的回答。5. 常见问题排查与进阶配置即使按照指南操作也可能会遇到一些问题。这里我整理了常见的“坑”及其解决方法。5.1 连接与认证问题问题现象可能原因排查步骤与解决方案AI助手完全无法识别Substack工具或提示“服务器错误”。1. MCP服务器启动失败。2. 客户端配置路径错误。3. 环境变量未正确传递。1.手动测试服务器在终端进入项目目录运行SUBSTACK_API_KEY你的密钥 node dist/index.js。观察是否有错误输出。常见的错误是Node版本过低或依赖缺失根据提示解决。2.检查路径确保配置文件中args数组里的dist/index.js路径是绝对路径并且指向你项目编译后的正确位置。在终端使用pwdMac/Linux或cd后chdirWindows确认项目根目录然后拼接/dist/index.js。3.检查客户端日志Claude Desktop和Cursor通常有日志输出窗口或设置。查看日志中是否有关于MCP服务器启动失败的详细信息。AI可以识别工具但调用时返回Unauthorized(401) 错误。API密钥错误或格式问题。1.核对密钥确保配置的SUBSTACK_API_KEY的值与从Substack后台复制的完全一致没有多余的空格或换行。2.理解认证方式Substack Publisher API的认证方式是将API密钥直接放在Authorization请求头中前面不需要加Bearer这个词。substack-publisher-mcp已经处理好了这一点所以问题通常出在密钥本身错误或已失效。3.重新生成密钥如果怀疑密钥泄露或无效去Substack后台撤销旧密钥生成一个新密钥并更新配置文件。配置了多出版物但AI说“未找到出版物”或查询不到数据。1. 环境变量名不匹配。2. 出版物名称引用错误。1.检查变量名确保环境变量名严格遵循SUBSTACK_API_KEY_NAME格式NAME是你自定义的大写标识如MAIN。在配置中引用时工具参数publication的值也应该是这个NAME例如publication: MAIN。2.使用list_publications首先让AI调用这个工具它会返回服务器识别到的所有出版物名称列表。用这个列表中的名称作为publication参数值。5.2 数据与使用问题问题现象可能原因排查步骤与解决方案list_posts返回的文章数量很少或没有。1. 默认的maxResults限制。2. 日期范围设置不当。3. 文章类型过滤。1.指定maxResults在提问时明确要求例如“列出我最近50篇文章”。AI会在调用工具时设置maxResults: 50。2.明确日期范围Substack API可能默认返回最近有限的数据。通过startDate和endDate参数指定更宽的范围。3.检查type参数如果你设置了type: only_paid则只会返回付费专区文章。get_subscriber_counts返回的数据字段不全或为0。1. API数据延迟。2. 统计口径理解有误。1.理解延迟订阅者数量等数据可能存在1-2天的处理延迟。今天查询昨天的数据可能最准确。2.阅读API文档get_subscriber_counts返回的是每日结束时的订阅者存量快照而不是当日新增数。新增数需要自己计算相邻日期的差值。get_post_stats中的new_free_subscriptions和new_paid_subscriptions才是该文章带来的增量。AI的回答看起来没有调用数据或数据过时。1. AI的上下文理解偏差。2. 缓存或会话问题。1.精确提问在提问中明确指出“使用Substack工具查询”。例如不要说“我的订阅者多少”而说“使用Substack工具查询我上个月的订阅者总数变化”。2.开启新会话有时AI的会话中会有旧的上下文干扰。尝试开启一个新的聊天会话再提问。3.指令引导直接给出指令如“请调用get_subscriber_counts工具查询我过去7天的数据。”5.3 进阶安全与自动化考量API密钥安全永远不要将包含真实API密钥的配置文件提交到Git等版本控制系统。可以将配置文件放在版本控制忽略的文件中如.gitignore里添加claude_desktop_config.json或者使用环境变量引用。更安全的方式是在配置文件中引用一个环境变量名而在系统层面设置该环境变量。// 配置文件可提交 { mcpServers: { substack: { command: node, args: [/path/to/dist/index.js], env: { SUBSTACK_API_KEY: $SUBSTACK_API_KEY_FROM_ENV } } } }然后在启动Claude Desktop前在终端设置环境变量临时或写入shell配置文件永久。速率限制Substack Publisher API有调用频率限制。虽然对于个人日常查询通常不会触发但如果你让AI进行非常复杂的历史数据批量分析例如循环查询几百篇文章的详情则可能被限流。substack-publisher-mcp服务器本身没有内置限流因此需要你在提问时保持合理的数据范围。如果遇到429错误说明触发了限流需要等待一段时间再试。错误处理与日志目前服务器的错误信息会通过MCP协议返回给客户端最终体现在AI的回答或客户端日志中。对于调试在启动服务器时添加NODE_ENVdevelopment环境变量或者查看项目的源码可能会看到更详细的日志输出逻辑。复杂的错误需要结合客户端日志和服务器端输出来判断。通过这套工具链你将Substack的数据洞察能力无缝嵌入了你的AI增强工作流中。它节省的不仅仅是点击鼠标的时间更是上下文切换的认知负荷让你能更专注于从数据中获取洞见而非忙于收集数据本身。