简体中文

MCP 接入

开启星球助手的 MCP 服务后，可以把本地已备份的星球数据交给 AI agent（Hermes、WorkBuddy、Claude Code、Cursor 等）直接调用：AI 会按你的自然语言指令自动检索帖子、导出文档、控制下载。

MCP 是什么

MCP（Model Context Protocol）是 AI agent 与工具服务交互的开放协议。开启星球助手的 MCP 服务后，AI agent 可以直接：

检索已备份的星球内容：搜索帖子、查看全文与评论、星球列表、数据统计
导出帖子为 Markdown / Word / PDF
控制下载：打开星球开始抓取、暂停、恢复、停止、查询进度
管理星球链接：新增、删除

共 13 个工具，AI 会根据你的自然语言指令自动选择调用。

Hermes 通过 MCP 检索星球数据

上图以 Hermes 为例：一句指令让 AI 在「老潘」星球里搜索所有包含「收笔」的帖子，AI 自动连续调用 list_planets、search_topics、get_topic 等工具完成检索并汇总结果。

启用步骤

打开星球助手，进入「设置」页面
找到「MCP 服务器 (AI agent 接入)」区块，勾选「启用 MCP 服务器」，服务立即启动（以输入框当前的 IP / 端口为准），开关旁显示绿色的 ● 运行中: http://127.0.0.1:8621/mcp
确认监听 IP（默认 127.0.0.1，即仅本机可访问）与端口（默认 8621）
点击「保存设置」，把启用状态与 IP / 端口持久化，下次启动软件会按此配置自动启动 MCP 服务

补充说明：

取消勾选后服务立即停止（显示灰色的「○ 已停止」），勾选与取消勾选都不需要点击保存
修改 IP / 端口后，需要取消勾选再重新勾选，服务才会以新地址运行（保存只写入配置，不重启服务）
状态标签实时显示运行状态；若服务因端口冲突等异常退出，标签会在 2 秒内自动纠正为「已停止」

接入 AI 客户端

MCP 端点地址：http://127.0.0.1:8621/mcp（如果改过 IP / 端口，以设置页状态标签显示的地址为准）。

Claude Code

claude mcp add --transport http planet-helper http://127.0.0.1:8621/mcp

添加后即可在对话里直接使用，例如：

帮我在星球助手里搜索最近关于"复盘"的帖子，并把前 10 条导出成 PDF

Cursor

在 ~/.cursor/mcp.json（全局）或项目的 .cursor/mcp.json 中添加：

{
  "mcpServers": {
    "planet-helper": {
      "url": "http://127.0.0.1:8621/mcp"
    }
  }
}

Hermes

命令行添加，URL 填端点地址：

hermes mcp add planet-helper --url http://127.0.0.1:8621/mcp

执行过程中会询问该服务是否需要认证，星球助手无需认证，直接选「否」。也可以直接写入 ~/.hermes/config.yaml：

mcp_servers:
  planet-helper:
    url: http://127.0.0.1:8621/mcp

添加后即可在对话里直接下指令，本文上方的截图就是 Hermes 的实际使用效果。可用 hermes mcp test planet-helper 检查连通性。

WorkBuddy

WorkBuddy 在图形界面里配置：进入「连接器」页面，点击右上角的「自定义连接」，在弹出的「MCP 服务管理」窗口中点击「配置 MCP」。

WorkBuddy 打开 MCP 服务管理

在配置文件（~/.workbuddy/mcp.json）中填入以下内容，点击「保存」即可：

{
  "mcpServers": {
    "planet-helper-mcp": {
      "url": "http://localhost:8621/mcp",
      "disabled": false
    }
  }
}

在 WorkBuddy 中配置星球助手 MCP

其他 MCP 客户端

任何支持 Streamable HTTP 传输的 MCP 客户端都可直接连接该端点，无需 token 或账号密码。调试可用官方 MCP Inspector：

npx @modelcontextprotocol/inspector

在 Inspector 界面选择 Streamable HTTP，填入端点地址，即可逐个测试工具。

监听 IP 与安全

监听 IP	效果	适用场景
`127.0.0.1`（默认）	仅本机可访问	绝大多数场景（AI 客户端与星球助手在同一台电脑）
`0.0.0.0` 或局域网 IP	同网络的其他设备也可访问	仅在受信任的局域网内使用远程 agent

重要提醒

MCP 服务没有密码 / token 认证。一旦把监听 IP 改为 0.0.0.0，同一网络里的任何设备无需凭据即可访问你电脑上已备份的全部星球数据（含帖子全文、评论、附件下载等能力）。请仅在完全可信的网络环境下使用，用完后改回 127.0.0.1。

使用注意事项

搜索分页：小心撑爆 AI 的上下文窗口

搜索工具的「每页条数」默认 20，你可以在对话中要求不设上限。你可以让 AI 一次取几百上千条，但每页过大时返回的 JSON 会迅速占满 LLM 的上下文窗口，导致：

AI 忘记你之前说的话（上下文被挤掉）
响应变慢、费用升高
超过模型上下文上限时直接报错

更好的做法是让 AI 循环分页读取，例如：

用每页 20 条的方式循环搜索"成长"相关的帖子，直到取完，然后给我汇总一份主题清单

这样 AI 会用「跳过条数 + 每页条数」逐页获取，内存平稳、上下文可控。是否加大每页条数由你自己权衡。

批量导出：量大时非常耗时，严重时会假死

批量导出没有条数限制，但导出是 CPU 密集操作（尤其 PDF 渲染和图片处理）：

几十条：几秒到几十秒
几千条以上：可能需要几分钟到数十分钟至更久，最严重时会造成星球助手界面无响应（导出仍在后台进行）

建议先用搜索确认符合条件的帖子数量，再决定导出范围；超大范围请按星球、按时间段分批导出。导出期间尽量不要同时操作软件的其他功能。

下载控制的特性

「打开星球」会启动一个浏览器窗口，需要等待你扫码登录知识星球（默认等待 15 秒，可在设置中调整），登录后才会开始自动抓取
「暂停下载」不是立即静止：软件会先收尾当前批次（最多再处理 1 个帖子 / 1 个附件），日志出现「已完全暂停」后才真正停止；被跳过帖子的图片 / 附件本次不会下载（帖子数据本身已入库），恢复下载后可刷新页面或「自动抓新」重新拉取
下载控制工具必须在星球助手软件在线时使用，MCP 服务内嵌在软件里，软件关闭后 agent 无法控制下载
试用版授权下，每个会话最多下载 5 个附件（AI 查询下载状态时会看到剩余额度）

其他提示

导出的文件统一存放在软件的「导出目录」（设置页可查看路径），AI 会告诉你具体输出位置
检索操作走软件本地数据库，不访问网络
同时连接多个 AI 客户端是支持的（每个客户端一个会话）

故障排查

现象	可能原因与处理
保存启用后弹「端口已被占用」	8621（或你设置的端口）被其他程序占用；换一个端口重新保存
设置页显示「○ 已停止」但配置为启用	服务异常退出（端口冲突 / 系统休眠等）；重新点一次「保存设置」即可重启
AI 客户端连不上	确认星球助手已启动、设置页状态标签为「● 运行中」；确认客户端里填的地址与标签一致
修改 IP 为 0.0.0.0 后远程连不上	检查操作系统防火墙是否放行该端口；确认两台设备在同一网络
AI 提示「GUI 尚未就绪」	软件刚启动还没完成初始化，稍等几秒重试
搜索没有结果	该关键词在已备份的帖子里不存在；先在软件里下载 / 抓取对应星球内容

大纲

MCP 接入#

MCP 是什么#

启用步骤#

接入 AI 客户端#

Claude Code#

Cursor#

Hermes#

WorkBuddy#

其他 MCP 客户端#

监听 IP 与安全#

使用注意事项#

搜索分页：小心撑爆 AI 的上下文窗口#

批量导出：量大时非常耗时，严重时会假死#

下载控制的特性#

其他提示#

故障排查#