postmd-mcp-server

PostMD MCP サーバー

PostMD 用の Model Context Protocol サーバーです。**Markdown ドキュメントを公開してリンクで共有できるウェブページを取得し、閲覧者が表示するドキュメントのグラフを追加できます。**グラフには、読み進める順序、ドキュメントで名前が挙げられている本文やルール、章をまたぐ手順などを示せます。任意でグループ、ドキュメントのパスワード、閲覧テーマも設定できます。このサーバーは PostMD の公開 API（/api/v1）をラップし、アシスタントがドキュメントを公開、閲覧、更新、整理できるようにします。

**アカウントもキーも不要で公開できます。**設定不要で、このサーバーはすでに Markdown を共有可能なページに変換できます。また、ホスト型サーバー https://postmd.turink.com/mcp もインストール不要です。API キーを設定すると、ドキュメントのグループ分けやメモなどの管理機能を利用できます。

**保存期間は30日です。**ドキュメントの保存期間は30日（data.retainedUntil）で、ドキュメントを読み込むたびに30日延長されます（延長は1日1回まで）。パスワードのないドキュメントは誰でも更新または削除できます。パスワードで保護されたドキュメントには、パスワードまたは所有者の API キーが必要です。

各種情報の掲載先： /llms.txt には、サービスでできることと、それぞれの説明があるページが記載されています。まずはこちらをご覧ください。HTTP リファレンスは /docs/api、機械可読な仕様は /api-docs にあります。

ホスト型またはローカル

	ホスト型	ローカル
アドレス	https://postmd.turink.com/mcp	npx -y postmd-mcp-server
必要なもの	なし	Node.js 20 以降
ツール	5	すべての20個
API キー	受け付けません	任意。メンバー限定ツールで使用
クライアント	ChatGPT や claude.ai などのウェブのみのクライアントを含む、あらゆるクライアント	ローカルプロセスを実行できるクライアント

ホスト型サーバーでは API キーを受け取れないため、キー不要のツールのみを利用できます。 グループ、メモ、ディスク上のファイルを読み込むツールはローカル専用です。

設定

ローカルのみ。ホスト型サーバーはこれらの設定を読み込みません。すべて任意です。

変数	説明
POSTMD_BASE_URL	デフォルトは https://postmd.turink.com です。セルフホスト版／ローカル版を使う場合に設定します。オリジンのみを指定し、末尾にスラッシュは付けません。
POSTMD_API_KEY	以下でスコープが示されたツール用の pmk_… キーです。postmd.turink.com にサインインし、アカウント → API keys を開いて、必要なスコープを選択してください。読み取りと書き込みは独立しており、403 は通常、スコープが不足していることを意味します。
POSTMD_DEBUG	1／true／yes → stderr への追加ログ出力。

読み込み順序：このリポジトリの .env（存在する場合）は dotenv で読み込まれ、ホスト（例：MCP の env）ですでに設定されている変数は上書きされません。.env やキーをコミットしないでください。

ツール

以下の各ツールはすべてローカルサーバーで動作します。ホスト型サーバーでは次の5つを利用できます。 postmd_create_document、postmd_get_document、postmd_get_document_raw、postmd_update_document、postmd_delete_document。

公開と閲覧 — キー不要：

ツール	用途
postmd_create_document	Markdown を公開し、docCode と共有 URL を取得
postmd_create_document_from_file	同じ機能ですが、このサーバーがローカルの filePath を読み込みます（大きなファイル向け）
postmd_get_document	docCode を指定してメタデータを取得
postmd_get_document_raw	保存された Markdown 本文を取得（password は任意）

ドキュメントの管理 — documents:write を持つキーが必要です（または、パスワードなしの所有者不在ドキュメントには、パスワードまたは認証情報なしでアクセスできます）。

ツール	用途
postmd_update_document	内容やメタデータを置き換えます。パスワードの解除も可能です
postmd_update_document_from_file	同じ機能ですが、本文はローカルの filePath から読み込みます
postmd_delete_document	ドキュメントを削除します（取り消し不可）
postmd_create_documents_from_files	1回の呼び出しで複数の .md ファイルを一括公開
postmd_move_document_to_group	ドキュメントをグループに移動

グラフ

PostMD ドキュメントには、ビューアーが描画するグラフデータを含めることができ、ドキュメントの各部分の関係を示します。グラフを作成または編集するツールはありません。グラフ用のエンドポイントがないためです。データは HTML コメントとして Markdown 内に保存され、本文とともに扱われます。

したがって、既存のドキュメントにグラフを追加するには、postmd_get_document_raw で読み込み、コメントを挿入してから、本文全体を postmd_update_document で送信します。グラフ付きの新しいドキュメントを公開する場合は、通常の postmd_create_document 呼び出しを使います。

形式については https://postmd.turink.com/docs/graph をご覧ください。ノードの内容やその接続方法を判断するにはドキュメントを読む必要があり、それは呼び出し元のエージェントの役割です。PostMD は見つけた内容を描画するだけです。

ファイル内にコードを保持する

Markdown ファイルには、公開時に割り当てられたドキュメントのコードを、先頭に postmd:document という印を付けた HTML コメントとして含めることができます。後のセッションでそのファイルを開いたとき、アドレスを指定されなくても、どのドキュメントを更新すべきか判断できます。形式については https://postmd.turink.com/docs/api の「ファイル内にコードを保持する」をご覧ください。ここにあるツールはコメントを書き込みません。呼び出し元のエージェントが自身のファイルを編集します。

ノートがあるドキュメントのコンテンツを置き換える

ノートは保存された位置ではなく、引用したテキストによって特定されます。そのため、ドキュメントの本文を置き換えると、ノートの参照先が移動したり失われたりします。引用文がなくなったノートは本文内の位置を失い、引用文が別の場所に現れるようになったノートは、そちらを指すようになります。どちらの場合も、引用文を含むノート自体は保持されます。

新しいコンテンツを送信する場合、どちらの更新ツールでも notesOnReplace が必要です。

値	効果
keep	コンテンツを置き換え、ノートはそのままにします
abort	ドキュメントのテキストにアンカーされたノートがある場合は拒否し、その数を通知します

メタデータのみの更新には指定しません。

ノートとハイライト — documents:read / documents:write スコープのキーを使用します。ノートは引用箇所にアンカーされたテキストです。ハイライトは色のみを付けた同じオブジェクトです。表示範囲は所有者によって決まります。キー所有者自身のドキュメントでは、ノートは PRIVATE または SHARED になり、他のユーザーのドキュメントでは常に SHARED です。所有者のいないドキュメント（匿名アップロードやサービス所有のページ）にはノートを付けられません。

ツール	目的
postmd_list_notes	ドキュメント上のノート：自分のノートと、すべての SHARED ノート
postmd_add_note	引用箇所にノート、または色のみのハイライトを追加します
postmd_update_note	自分が書いたノートを編集します
postmd_resolve_note	SHARED の議論を解決済みにする、または再開します
postmd_delete_note	自分のノート、または自分のドキュメント上の SHARED ノートを削除します
postmd_list_my_notes	すべてのドキュメントにある自分のノート

グループ — groups:read / groups:write スコープのキーを使用します。

ツール	目的
postmd_list_groups	キーから見えるグループ（ページ分割）
postmd_list_group_documents	グループ内のドキュメント（ページ分割、検索可能、並べ替え可能）
postmd_create_group	新しいグループを作成します
postmd_update_group	グループ名を変更します
postmd_delete_group	グループを削除します（ドキュメントは残ります）

アップロードするには、Markdown 全文を markdown 引数として渡すか、ローカルの filePath のみを渡してこのサーバーにファイルを読み込ませます。パスは MCP サーバーを実行しているマシン上に存在している必要があります。

クライアントの設定

ホスト型

Claude Code：

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

JSON 設定を受け付けるクライアント：

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

ChatGPT では Settings → Apps の下に追加し、claude.ai では Settings → Connectors の下に追加します。 認証は不要です。

ローカル

インストールは不要です。npx がパッケージを取得し、クライアントが起動します。

Claude Code：

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

Cursor（~/.cursor/mcp.json）およびほとんどの stdio クライアント：

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

チェックアウトしたコードを実行する場合（コードを変更するときや、ローカルの PostMD に対してデバッグするとき）は、 クライアントにファイルを指定します。

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"

公開／読み取り専用で使用する場合は、env を完全に省略してください。cp .env.example .env でも構いません。サーバーは自身の .env を読み込みます。

npx -y postmd-mcp-server を手動で実行して確認できるのは、起動することだけです。MCP を標準入力と標準出力経由でやり取りするため、クライアントを待機し続けます。

スモークテスト

稼働中のサーバーに対して書き込み処理全体を実行し、終了後に後片付けをします。4 つすべてのスコープを持つキーが必要です。

export POSTMD_API_KEY=pmk_…
npm run smoke

グループとパスワード付きドキュメントを作成し、読み戻して更新し、パスワードを解除した後、両方を削除します。また、認証情報なしでドキュメントを 1 つ公開し、トークンなしで削除します。

スタック

@modelcontextprotocol/sdk 1.30.0、dotenv。ライセンス： MIT。