Postmd Mcp Server

io.github.reinlainerPublished by GitHub account reinlainerv2.6.1Updated Oct 25, 2026

Publish Markdown as a shareable web page, with document graphs

VerifiedStreamable HTTPWeb executableProductivity & WorkflowFiles & Storage

Overview

AI-generated overview

Publishes Markdown as a shareable PostMD web page and reads, updates, deletes and organizes those documents, with optional notes and groups.

What you can do
Publish Markdown as a web page and get a document code and share link, from text or a local file, including bulk publishing several files at once and moving documents into groups (local server only). Read document metadata and the stored Markdown source, with a password for protected documents. Replace a document's content or metadata, clear its password, or delete it. Manage notes and highlights anchored to quoted passages, including resolving and listing them across documents. Create, rename and delete groups and list their documents.
When to use it
Useful when you want an assistant to turn Markdown notes or drafts into a link you can share, or to keep a set of published documents updated and organized. The hosted endpoint is enough for publish-and-read work; the local package adds file-based uploads, notes and groups.
Requirements
Either the hosted HTTP endpoint, which needs nothing and accepts no API key, or the npm package run locally with Node.js 20 or later. Optional local variables: POSTMD_API_KEY for document management, notes and groups; POSTMD_BASE_URL for a self-hosted instance; POSTMD_DEBUG for diagnostics. Network access to the PostMD service.
Before you install
Documents without a password can be updated or deleted by anyone who has the link, so use a password for anything that matters. Documents expire after 30 days unless read, which extends retention. Deleting a document cannot be undone. Replacing content on a document with notes requires choosing whether to keep or abort. The API key grants read and write scopes and should not be committed to a repository.

Installation

In SourceWeft

  1. Open Postmd Mcp Server in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.reinlainer%2Fpostmd-mcp-server/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

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

Source: README.md at commit 9ef80c3

Tools

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.

ParameterstitlegroupIdfileNamemarkdownrequiredpasswordviewerStyle

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.

ParametersdocCoderequired

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`.

ParametersdocCoderequiredpassword

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.

ParameterstitledocCoderequiredfileNamemarkdownpasswordviewerStyleclearPasswordnotesOnReplacecurrentPassword

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.

ParametersdocCoderequiredpassword

Version history

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

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts