postmd-mcp-server

PostMD MCP 服务

PostMD 的模型上下文协议服务端——发布 Markdown 文档，获取可通过链接分享的网页，并添加文档图谱供查看器绘制：阅读顺序、文档提及的实体和规则，以及分布在各章节中的流程。支持可选的分组、文档密码和查看器主题。此服务端封装了 PostMD 的公共 API（/api/v1），让助手能够发布、读取、更新和整理文档。

发布无需账户和密钥。 无需任何配置，此服务端即可将 Markdown 转换为可分享的网页；托管服务端 https://postmd.turink.com/mcp 也无需安装。API 密钥可用于管理文档：将文档整理到分组中，以及添加备注。

保留 30 天。 文档的保留期限为 30 天（data.retainedUntil）；每次读取都会延长 30 天（每天最多延长一次）。没有密码的文档可由任何人更新或删除；受密码保护的文档则需要密码或所有者的 API 密钥。

相关文档： /llms.txt 列出了服务的功能，以及各项内容对应的页面；请从这里开始。/docs/api 是 HTTP 参考文档，/api-docs 是机器可读的规范。

托管或本地

	托管	本地
地址	https://postmd.turink.com/mcp	npx -y postmd-mcp-server
需要	无	Node.js 20 或更高版本
工具	5 个	全部 20 个
API 密钥	不接受	可选，用于需要成员权限的工具
客户端	任意客户端，包括仅支持 Web 的客户端，如 ChatGPT 和 claude.ai	任意可运行本地进程的客户端

托管服务端无法接收 API 密钥，因此只提供无需密钥的工具。分组、备注以及读取磁盘文件的工具仅限本地使用。

配置

仅限本地使用——托管服务端不会读取这些变量。它们均为可选项。

变量	说明
POSTMD_BASE_URL	默认为 https://postmd.turink.com。用于可自托管／本地实例。仅填写源地址，不带末尾斜杠。
POSTMD_API_KEY	用于下方标注了权限范围的工具，格式为 pmk_…。登录 postmd.turink.com，打开 账户 → API 密钥，选择所需权限范围——读取和写入权限彼此独立；出现 403 通常意味着缺少所需权限。
POSTMD_DEBUG	设置为 1／true／yes → 在 stderr 中输出额外日志。

加载顺序：此仓库的 .env（如果存在）会通过 dotenv 加载，且不会覆盖主机已设置的变量（例如 MCP env）。请勿提交 .env 或密钥。

工具

以下所有工具都可在本地服务端使用。托管服务端提供其中 5 个： postmd_create_document、postmd_get_document、postmd_get_document_raw、postmd_update_document 和 postmd_delete_document。

发布和读取——无需密钥：

工具	用途
postmd_create_document	发布 Markdown，获取 docCode 和分享 URL
postmd_create_document_from_file	功能相同，但由此服务端读取本地 filePath（适用于大型文件）
postmd_get_document	根据 docCode 获取元数据
postmd_get_document_raw	获取存储的 Markdown 正文（可选提供 password）

管理文档——需要拥有 documents:write 权限的密钥（对于不属于任何人的无密码文档，也可使用密码或不提供凭据）：

工具	用途
postmd_update_document	替换内容和／或元数据；可清除密码
postmd_update_document_from_file	功能相同，正文从本地 filePath 读取
postmd_delete_document	删除文档（无法撤销）
postmd_create_documents_from_files	在一次调用中批量发布多个 .md 文件
postmd_move_document_to_group	将文档移入分组

图表

PostMD 文档可以包含图表数据，由查看器绘制，以展示文档各部分之间的关系。这里没有工具可以创建或编辑图表，因为没有对应的端点：数据以 HTML 注释的形式存放在 Markdown 中，并随正文一起传递。

因此，要为现有文档添加图表，需要使用 postmd_get_document_raw 读取文档，插入注释，再使用 postmd_update_document 发送完整正文。发布带有图表的新文档则只需进行常规的 postmd_create_document 调用。

格式见 https://postmd.turink.com/docs/graph。确定节点以及它们之间的连接方式需要读取文档，这是调用方 Agent 的工作；PostMD 只会绘制它找到的内容。

将代码保存在文件中

Markdown 文件可以在顶部通过标记为 postmd:document 的 HTML 注释，保存其发布时对应的文档代码。之后打开该文件的会话无需提供地址，就能知道要更新哪个文档。格式见 https://postmd.turink.com/docs/api 中的“将代码保存在文件中”。这里没有工具会写入该注释；调用方 Agent 需要编辑自己的文件。

替换带有注释的文档内容

注释根据其引用的文本定位，而非根据存储的位置定位。因此，替换文档正文会改变或丢失注释的指向位置：引用内容已不存在的注释会失去在正文中的位置；引用内容现在出现在其他位置的注释则会指向那里。无论哪种情况，注释本身（包括引用文本）都会保留。

发送新内容时，两个更新工具都要求提供 notesOnReplace。

值	效果
keep	替换内容，并保持注释不变
abort	如果文档有锚定在文本上的注释，则拒绝操作，并说明注释数量

仅更新元数据时无需提供该参数。

注释和高亮 — 使用 documents:read / documents:write 权限。注释是锚定到引用段落的文本；高亮是仅带有颜色的同类对象。可见范围由所有权决定：在密钥持有者自己的文档中，注释为 PRIVATE 或 SHARED；在其他人的文档中，注释始终为 SHARED。无人拥有的文档 — 匿名上传和服务所有的页面 — 不接受注释：

工具	用途
postmd_list_notes	查看文档上的注释：你自己的注释以及所有 SHARED 注释
postmd_add_note	为引用段落添加注释或仅带颜色的高亮
postmd_update_note	编辑你撰写的注释
postmd_resolve_note	将 SHARED 讨论标记为已解决，或重新开启讨论
postmd_delete_note	删除你自己的注释，或删除你文档上的 SHARED 注释
postmd_list_my_notes	查看你在所有文档上的注释

群组 — 使用 groups:read / groups:write 权限：

工具	用途
postmd_list_groups	查看密钥可见的群组（分页）
postmd_list_group_documents	查看群组中的文档（分页、可搜索、可排序）
postmd_create_group	创建群组
postmd_update_group	重命名群组
postmd_delete_group	删除群组（文档会保留）

上传时：可以将完整的 Markdown 作为 markdown 参数传入，也可以只传入本地 filePath，由此 MCP 服务读取文件。该路径必须存在于运行 MCP 服务的机器上。

客户端配置

托管式

Claude Code：

claude mcp add --transport http postmd https://postmd.turink.com/mcp

支持 JSON 配置的客户端：

{
  "mcpServers": {
    "PostMD": {
      "type": "http",
      "url": "https://postmd.turink.com/mcp"
    }
  }
}

在 ChatGPT 中，将其添加到 Settings → Apps；在 claude.ai 中，将其添加到 Settings → Connectors。 无需进行任何授权。

本地

无需安装：npx 会获取软件包，客户端会启动它。

Claude Code：

claude mcp add postmd -- npx -y postmd-mcp-server

Cursor（~/.cursor/mcp.json）和大多数其他 stdio 客户端：

{
  "mcpServers": {
    "PostMD": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "postmd-mcp-server"],
      "env": { "POSTMD_API_KEY": "pmk_…" }
    }
  }
}

若要运行本地检出版本——修改代码，或针对本地 PostMD 进行调试—— 请让客户端指向该文件。

git clone https://github.com/reinlainer/postmd-mcp-server.git
cd postmd-mcp-server && npm ci
claude mcp add postmd-dev -- node "$PWD/src/index.js"

用于发布或只读时，请完全省略 env。也可以运行 cp .env.example .env——服务会加载自己的 .env。

手动运行 npx -y postmd-mcp-server 只能检查它是否能启动。它通过 stdin 和 stdout 进行 MCP 通信，因此会一直等待客户端连接。

冒烟测试

针对运行中的服务执行完整写入流程，并在结束后清理。需要具有全部四种权限范围的密钥。

export POSTMD_API_KEY=pmk_…
npm run smoke

它会创建一个分组和一个设有密码的文档，读取文档、更新文档、清除密码，然后删除两者。它还会在没有凭据的情况下发布一个文档，并在不使用令牌的情况下将其删除。

技术栈

@modelcontextprotocol/sdk 1.30.0、dotenv。许可证： MIT。