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 分