io.github.reinlainer/postmd-mcp-server

Attach a note or highlight to a document. Requires an API key with documents:write. Give `content` for a note, `color` alone for a colour-only highlight (then `quotedContent` is required — a highlight must point at a passage). Visibility comes from ownership: on the key member's own document choose PRIVATE (only they see it) or SHARED; on anyone else's document every note is SHARED, so omit scope. Documents nobody owns — anonymous uploads and service-owned pages — take no notes at all.

Publish Markdown as a PostMD web page. No API key required — anyone can publish. Returns docCode and data.shareUrl; hand shareUrl to people. Without a key the document is anonymous: data.retainedUntil is when it is deleted and data.controlToken is the only way to update or delete it, shown once and never reissued — report both to the person. With an API key the document belongs to that member, has no expiry, needs no token and can collect notes; groupId files it into that group instead of the default one (key with documents:write).

Same as postmd_create_document, but reads the Markdown from filePath on the machine running this MCP server — use it for large files instead of pasting the body. Without an API key it returns data.controlToken and data.retainedUntil, same as above.

Publish several .md files in one call (bulk upload). Requires an API key with documents:write. The outer resultCode is 200 even if some files failed — check data.succeeded and each entry in data.results.

Create a group. Requires an API key with groups:write. Documents can then be filed into it and members invited from the web app.

Delete a document. Requires an API key with documents:write for a document you own, or `controlToken` for an anonymously published one. There is no endpoint to undo this: the document stops being served at once and its stored content is erased about a month later.

Delete a group. Owner only; the default group cannot be deleted. Documents in it are not deleted. Requires an API key with groups:write.

Delete a note: your own, or a SHARED note on a document you own. Requires an API key with documents:write.

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

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

List documents in a group. Requires an API key with groups:read and documents:read. Paged; q searches title and file name (substring, case-insensitive).

List groups the key's member belongs to. Requires an API key with groups:read. Paged.

List every note the key's member wrote, across all documents, with docCode and documentTitle beside each one. Requires an API key with documents:read.

List notes and highlights on a document: your own plus every SHARED one, newest first. Requires an API key with documents:read. Each note carries mine and manageable flags — trust them instead of re-deriving permissions. Pass `password` for a password-protected document.

Move a document you own into a group you can use, optionally into a folder of that group. A document belongs to exactly one group, so this replaces its current group. Requires an API key with documents:write.

Mark a note as settled, or undo it with resolved=false. Meaningful on SHARED notes; the author or the document owner may set it. Requires an API key with documents:write.

Update a document. Requires an API key with documents:write for a document you own, or `controlToken` for an anonymously published one. Include `markdown` to replace the stored content; any metadata field replaces that field. clearPassword / clearShareEndDate remove the password / end date. Updating does not push back the deletion date of an anonymous document. Replacing the content requires notesOnReplace.

Same as postmd_update_document, but reads the new Markdown from filePath on the machine running this MCP server. Takes `controlToken` the same way.

Rename a group or change its expiry. Owner only. Requires an API key with groups:write. clearExpireDate removes the expiry.

Edit a note you wrote. Requires an API key with documents:write. Omitting scope keeps the current one; a scope you do send follows the ownership rule above. The note must keep text or a colour.

Upload an image or PDF to reference from a document. Requires an API key with documents:write. Allowed types: png, jpg, jpeg, gif, webp, svg, bmp, pdf. Use the returned data.url as the image/link target in your Markdown, then publish the Markdown with postmd_create_document.