postmd-mcp-server

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

	Hosted	Local
Address	https://postmd.turink.com/mcp	npx -y postmd-mcp-server
Needs	nothing	Node.js 20 or later
Tools	5	all 20
API key	not accepted	optional, for member-scoped tools
Clients	any, including web-only ones such as ChatGPT and claude.ai	any 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.

Variable	Description
POSTMD_BASE_URL	Defaults to https://postmd.turink.com. Set for a self-hosted / local instance. Origin only, no trailing slash.
POSTMD_API_KEY	pmk_… 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_DEBUG	1 / 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:

Tool	Purpose
postmd_create_document	Publish Markdown, get docCode + share URL
postmd_create_document_from_file	Same, but this server reads a local filePath (large files)
postmd_get_document	Metadata by docCode
postmd_get_document_raw	Stored Markdown body (optional password)

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

Tool	Purpose
postmd_update_document	Replace content and/or metadata; can clear password
postmd_update_document_from_file	Same, body read from a local filePath
postmd_delete_document	Delete a document (no undo)
postmd_create_documents_from_files	Bulk-publish several .md files in one call
postmd_move_document_to_group	Move 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.

Value	Effect
keep	Replaces the content and leaves the notes as they are
abort	Refuses 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:

Tool	Purpose
postmd_list_notes	Notes on a document: yours + every SHARED one
postmd_add_note	Attach a note, or a colour-only highlight to a quoted passage
postmd_update_note	Edit a note you wrote
postmd_resolve_note	Mark a SHARED discussion settled, or reopen it
postmd_delete_note	Delete yours, or a SHARED note on your document
postmd_list_my_notes	Your notes across every document

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

Tool	Purpose
postmd_list_groups	Groups visible to the key (paged)
postmd_list_group_documents	Documents in a group (paged, searchable, sortable)
postmd_create_group	New group
postmd_update_group	Rename group
postmd_delete_group	Delete 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:

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

Clients that take a JSON config:

{
  "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:

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

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

{
  "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.

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"

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.

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.