Postmd Mcp Server

io.github.reinlainer由 GitHub 账号 reinlainer 发布v2.6.1更新于 Oct 25, 2026

Publish Markdown as a shareable web page, with document graphs

已验证Streamable HTTP可网页运行效率与工作流文件与存储

概览

AI 生成的概览

把 Markdown 发布为可分享的 PostMD 网页,并可读取、更新、删除和整理这些文档,可选支持批注与分组。

可以做什么
把 Markdown 发布为网页,获得文档代码和分享链接,可从文本或本地文件发布,支持一次批量发布多个文件以及把文档移入分组(仅本地服务器)。读取文档元数据和已存储的 Markdown 原文,受密码保护的文档需提供密码。替换文档内容或元数据、清除密码或删除文档。管理锚定到引用段落的批注和高亮,包括标记已解决以及跨文档列出批注。创建、重命名和删除分组,并列出分组内的文档。
适用场景
适合让助手把 Markdown 笔记或草稿变成可分享的链接,或持续更新和整理一批已发布的文档。托管端点足以完成发布和读取;本地包额外提供基于文件的上传、批注和分组。
运行要求
可使用托管 HTTP 端点,无需任何配置,也不接受 API 密钥;或使用 npm 包在本地运行,需要 Node.js 20 或更高版本。本地可选变量:POSTMD_API_KEY 用于文档管理、批注和分组;POSTMD_BASE_URL 用于自建实例;POSTMD_DEBUG 用于诊断日志。需要能访问 PostMD 服务的网络。
安装前请注意
无密码的文档,任何拿到链接的人都能更新或删除,重要内容应设置密码。文档 30 天后过期,被读取可延长保留期。删除文档无法撤销。替换带批注文档的内容时必须选择保留还是中止。API 密钥带有读写权限,不应提交到代码仓库。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Postmd Mcp Server,将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Web executable,通过 Streamable HTTP。 远程服务在工作区中配置后即可从网页运行时运行。

交给智能体安装

把这段提示词粘贴到 Claude Code、Codex、Cursor 等智能体,或 SourceWeft 对话中。智能体会读取该服务器的安装指南,先向你展示发布者、端点和登录方式,经你同意后再把它添加到你的客户端。密钥不会写进任何命令。

阅读 https://sourceweft.com/mcp/io.github.reinlainer%2Fpostmd-mcp-server/install.md,并按其中说明把这个 MCP 服务器接入我的客户端。修改任何配置之前,先告诉我它的发布者、端点和登录方式,等我确认。不要把 API 密钥写进命令或我会提交的文件;问我密钥应从哪里获取。

查看智能体所依据的安装指南

其他 MCP 客户端

把它添加到你客户端的 mcpServers 配置中。

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

README

PostMD MCP Server

Model Context Protocol server for PostMD — publish a Markdown document, get a web page you share by link, and add a document graph that the viewer draws: the reading order, the bodies and rules a document names, a procedure spread over its chapters. Optional groups, document passwords and viewer themes. This server wraps PostMD's public API (/api/v1) so assistants can publish, read, update and organize documents.

Publishing needs no account and no key. With zero configuration this server can already turn Markdown into a shareable page, and the hosted server at https://postmd.turink.com/mcp needs no install either. An API key adds management: organizing documents in groups, and notes.

30-day retention. Documents have a 30-day retention period (data.retainedUntil) that extends by 30 days whenever the document is read (at most once per day). Documents without a password can be updated or deleted by anyone; password-protected documents require the password or the owner's API key.

Where things are written down: /llms.txt lists what the service can do and which page answers each thing; it is the place to start. /docs/api is the HTTP reference and /api-docs the machine-readable spec.

Hosted or local

HostedLocal
Addresshttps://postmd.turink.com/mcpnpx -y postmd-mcp-server
NeedsnothingNode.js 20 or later
Tools5all 20
API keynot acceptedoptional, for member-scoped tools
Clientsany, including web-only ones such as ChatGPT and claude.aiany that can run a local process

The hosted server has no way to receive an API key, so it carries only the tools that need none. Groups, notes and the tools that read a file from your disk are local-only.

Configuration

Local only — the hosted server reads none of these. All are optional.

VariableDescription
POSTMD_BASE_URLDefaults to https://postmd.turink.com. Set for a self-hosted / local instance. Origin only, no trailing slash.
POSTMD_API_KEYpmk_… for the tools marked with a scope below. Sign in at postmd.turink.com, open Account → API keys, pick the scopes you need — read and write are independent, and a 403 usually means a missing scope.
POSTMD_DEBUG1 / true / yes → extra stderr logging.

Load order: this repo's .env (if present) is applied via dotenv without overwriting variables already set by the host (e.g. MCP env). Do not commit .env or keys.

Tools

Every tool below works on the local server. The hosted server carries five of them: postmd_create_document, postmd_get_document, postmd_get_document_raw, postmd_update_document, and postmd_delete_document.

Publishing and reading — no key needed:

ToolPurpose
postmd_create_documentPublish Markdown, get docCode + share URL
postmd_create_document_from_fileSame, but this server reads a local filePath (large files)
postmd_get_documentMetadata by docCode
postmd_get_document_rawStored Markdown body (optional password)

Managing documents — key with documents:write (or password / no credential for unowned documents without password):

ToolPurpose
postmd_update_documentReplace content and/or metadata; can clear password
postmd_update_document_from_fileSame, body read from a local filePath
postmd_delete_documentDelete a document (no undo)
postmd_create_documents_from_filesBulk-publish several .md files in one call
postmd_move_document_to_groupMove a document into a group

Graphs

A PostMD document can carry graph data that the viewer draws, showing how the parts of the document relate. No tool here creates or edits a graph, because there is no endpoint for one: the data sits in the Markdown as an HTML comment and travels with the body.

Adding a graph to an existing document therefore means reading it with postmd_get_document_raw, inserting the comment, and sending the whole body back with postmd_update_document. Publishing a new document with a graph is an ordinary postmd_create_document call.

The format is at https://postmd.turink.com/docs/graph. Working out what the nodes are and how they connect requires reading the document, which is the calling agent's part; PostMD only draws what it finds.

Keeping the code in the file

A Markdown file can carry the code of the document it was published as, in an HTML comment at its top marked postmd:document. A later session that opens the file can then tell which document to update without being given the address. The format is at https://postmd.turink.com/docs/api, "Keeping the code in the file". No tool here writes the comment; the calling agent edits its own file.

Replacing content on a document that has notes

Notes are located by the text they quote, not by a stored position. Replacing a document's body therefore moves or loses where they point: a note whose quote is gone loses its place in the body, and one whose quote now appears elsewhere points there instead. The note itself, including the quoted text, is kept either way.

Both update tools require notesOnReplace whenever new content is sent.

ValueEffect
keepReplaces the content and leaves the notes as they are
abortRefuses when the document has notes anchored to its text, and says how many

Metadata-only updates do not take it.

Notes and highlights — key with documents:read / documents:write. A note is text anchored to a quoted passage; a highlight is the same object carrying only a colour. Visibility comes from ownership: on the key member's own document a note is PRIVATE or SHARED, and on anyone else's document it is always SHARED. Documents nobody owns — anonymous uploads and service-owned pages — take no notes:

ToolPurpose
postmd_list_notesNotes on a document: yours + every SHARED one
postmd_add_noteAttach a note, or a colour-only highlight to a quoted passage
postmd_update_noteEdit a note you wrote
postmd_resolve_noteMark a SHARED discussion settled, or reopen it
postmd_delete_noteDelete yours, or a SHARED note on your document
postmd_list_my_notesYour notes across every document

Groups — key with groups:read / groups:write:

ToolPurpose
postmd_list_groupsGroups visible to the key (paged)
postmd_list_group_documentsDocuments in a group (paged, searchable, sortable)
postmd_create_groupNew group
postmd_update_groupRename group
postmd_delete_groupDelete a group (documents survive)

For uploads: either pass the full Markdown as the markdown argument, or pass a local filePath only so this server reads the file. The path must exist on the machine running the MCP server.

Client configuration

Hosted

Claude Code:

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

Clients that take a JSON config:

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

In ChatGPT, add it under Settings → Apps; in claude.ai, under Settings → Connectors. There is nothing to authorize.

Local

There is nothing to install: npx fetches the package and the client spawns it.

Claude Code:

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

Cursor (~/.cursor/mcp.json) and most other stdio clients:

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

To run a checkout instead — changing the code, or debugging against a local PostMD — point the client at the file.

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

Leave env out entirely for publish/read-only use. cp .env.example .env works too — the server loads its own .env.

Running npx -y postmd-mcp-server by hand only checks that it starts. It speaks MCP over stdin and stdout, so it will sit there waiting for a client.

Smoke test

Runs the full write path against a live server and cleans up after itself. Needs a key with all four scopes.

bash
export POSTMD_API_KEY=pmk_…npm run smoke

Creates a group and a passworded document, reads it back, updates it, clears the password, then deletes both. It also publishes one document with no credential and removes it without a token.

Stack

@modelcontextprotocol/sdk 1.30.0, dotenv. License: MIT.

来源:README.md,提交 9ef80c3

工具

5

postmd_create_document

Publish document

Publish Markdown as a PostMD web page. No API key required — anyone can publish. Returns docCode and data.shareUrl; hand shareUrl to people. Documents have a 30-day retention period (data.retainedUntil) that extends on each read. Documents without a password can be updated or deleted by anyone; password-protected documents require the password or the owner's API key. With an API key the document belongs to that member; groupId files it into that group (key with documents:write). The returned docCode can be kept at the top of the source file in a `postmd:document` comment (format at /docs/api) so a later session finds the document.

输入参数titlegroupIdfileNamemarkdown必填passwordviewerStyle

postmd_get_document

Get document info

Get document metadata by docCode: title, fileName, hasPassword, viewerStyle, timestamps. Public — no API key needed. Content is not included; use postmd_get_document_raw for the Markdown source.

输入参数docCode必填

postmd_get_document_raw

Get document source

Get the stored Markdown source of a document. Public — no API key needed. Password-protected documents need `password`.

输入参数docCode必填password

postmd_update_document

Update document

Update a document. Password-protected documents require the password or the owner's API key; documents without a password can be updated by anyone. Include `markdown` to replace the stored content; any metadata field replaces that field. clearPassword removes the password. Replacing the content requires notesOnReplace.

输入参数titledocCode必填fileNamemarkdownpasswordviewerStyleclearPasswordnotesOnReplacecurrentPassword

postmd_delete_document

Delete document

Delete a document. Password-protected documents require the password or the owner's API key; documents without a password can be deleted by anyone.

输入参数docCode必填password

版本历史

4
  1. v2.6.1最新Oct 4, 2026
  2. v2.6.0Sep 29, 2026
  3. v2.5.0Sep 28, 2026
  4. v2.4.0Sep 16, 2026

评分

已满足适用检查项的 100%

该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。

  • 近 30 天内可连通必需25 分
  • 已声明认证方式必需10 分
  • 已列出工具必需15 分
  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分