Markpin

@markpin/mcp

Markpin のフォルダー用 MCP サーバーです。Markpin は、ウェブページやクリップを Markdown ファイルとして、自分で管理するフォルダーに保存する Chrome 拡張機能です。このサーバーを使うと、AI クライアント（Claude Code、Claude Desktop、Cursor、…）からこれらのファイルを検索して読み取ることができ、必要に応じて確認を得たうえで編集できます。

• デフォルトでは読み取り専用です。書き込みには --allow-write と、変更のたびに確認ダイアログが必要です。
• stdio 経由でローカルで実行します。コンピューターの外にデータが送信されることはありません。
• フォルダーを監視するため、ブラウザーで保存したページは、再起動しなくても次のクエリに反映されます。

要件

• Node.js 20.1 以降（node -v）。
• 保存先の設定が Local folder または Google Drive になっている Markpin Chrome 拡張機能。Google Drive を使う場合は、フォルダーがディスク上に存在するよう、Google Drive for Desktop も必要です。

実行

npx -y @markpin/mcp --dir "<your Markpin folder>"

オプション：

フラグ	説明
--dir <path>	必須。Markpin フォルダー（pages/ を含むフォルダー）です。~ は展開されます。
--allow-write	10 個の書き込みツールを登録します。指定しない場合、サーバーは読み取り専用です。
--lang ko|en|ja|es|pt-BR|de|fr	確認ダイアログの言語です。デフォルトはシステムのロケールから取得します（pt* → pt-BR）。それ以外の場合は en です。Markpin 拡張機能のセットアップガイドでは、Chrome の言語に基づいてこの値が入力されます。

成功すると、サーバーは stderr に serving N pages from <dir> と出力します。stdout は MCP プロトコルに使われるため、すべてのログは stderr に出力されます。この行を見るのがパスを確認する最も手早い方法です。

Markpin フォルダーを探す

フォルダーには pages/ ディレクトリが必要です。ない場合は、まだ拡張機能から何もアップロードされていません。まず Chrome でページを保存してください。

Local folder — Markpin の設定で選択したフォルダーです。

• macOS：Finder でフォルダーを右クリックし、⌥ Option キーを押したまま Copy "…" as Pathname を選択します。
• Windows：Shift キーを押しながらフォルダーを右クリックし、Copy as path を選択します（前後の引用符を削除してください）。

Google Drive — Drive for Desktop は Drive の内容をディスクに同期します。Markpin フォルダーは My Drive の最上位にあります。名前は Google アカウントの言語に応じて異なります。My Drive（en）、내 드라이브（ko）、マイドライブ（ja）、Mi unidad（es）、Meu Drive（pt-BR）、Meine Ablage（de）、Mon Drive（fr）：

• macOS：~/Library/CloudStorage/GoogleDrive-<your email>/My Drive/Markpin
• Windows：G:\My Drive\Markpin（ドライブ文字は異なる場合があります。エクスプローラーで確認してください）

Chrome の Markpin 設定ページにある MCP setup guide ボタンを使うと、これらのパスと --lang を入力できます。

サーバーを登録する

<dir> をフォルダーのパスに置き換えます。書き込みツールを使う場合は、引数の末尾に --allow-write を追加してください。

Claude Code

claude mcp add -s user markpin -- npx -y @markpin/mcp --dir "<dir>"

-s user を指定するとすべてのプロジェクトに登録されます。このフラグを省略すると、現在のディレクトリだけに登録されます。

次に claude mcp list を実行すると、markpin: … - ✓ Connected と表示されます。

Claude Desktop

設定ファイルを編集します（Claude → Settings → Developer → Edit Config）。

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

macOS：

{
  "mcpServers": {
    "markpin": {
      "command": "npx",
      "args": ["-y", "@markpin/mcp", "--dir", "<dir>"]
    }
  }
}

Windows（Claude Desktop はシェルなしで起動するため、npx には cmd /c が必要です。パス内のバックスラッシュはエスケープしてください）：

{
  "mcpServers": {
    "markpin": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@markpin/mcp", "--dir", "G:\\My Drive\\Markpin"]
    }
  }
}

Claude Desktop を再起動します。チャットボックスのハンマー／プラグのアイコンに Markpin ツールが表示されます。

Cursor

同じ JSON を ~/.cursor/mcp.json（すべてのプロジェクト）または .cursor/mcp.json（1 つのプロジェクト）に追加し、Cursor Settings → MCP でサーバーを有効にします。

ファイル形式

各ページは1つのMarkdownファイルです。フロントマターには、ユーザー向けのキー（title、url、savedAt、tags、summary、readAt、deletedAt）のみが含まれるため、Obsidianなどのノートアプリではすっきりとしたプロパティパネルが表示されます。Markpinが内部で必要とする情報（id、rev、updatedAt、アンカー付きのクリップ、ブックマーク）は、ファイルの末尾にある1行のJSONブロックにすべて格納されます：

このブロックは手作業で編集しないでください。0.7.0より前に書き込まれたファイル（フロントマターにmarkpin: 1があるもの）も引き続き読み込まれ、次に変更が加えられた際に新しい形式で書き直されます。

markpin.json（Markdownテンプレート）

Markdownテンプレートを選択するか、オプションで.trash/を有効にすると、拡張機能はフォルダのルートにmarkpin.jsonを書き込みます。このサーバーは起動時と再スキャンのたびにこのファイルを読み込み、同じテンプレート（defaultまたはobsidian、あるいはカスタムテンプレート文字列）を使って書き込むファイルをレンダリングします。そのため、MCP経由で保存したページもブラウザーから保存したページと同じ見た目になります。変更されるのはフロントマターより下の本文のみで、フロントマターは常にMarkpin独自のものです。削除したファイルを.trash/に移動するのは、このサーバーではなく拡張機能です。

読み取り専用と--allow-write

--allow-writeを指定しない場合、サーバーが公開するのは4つの読み取りツールのみで、ファイルを変更することはできません。指定すると、10個の書き込みツールが追加されます。すべての書き込みには、次の3つのゲートがあります：

1. フラグ。 登録時に、書き込みを許可することを選択しています。
2. クライアントの権限。 ツールは読み取り専用ではないものとしてマークされます（delete_pagesは破壊的操作としてマークされます）。そのため、Claude Codeなどのクライアントは呼び出しごとに確認を求めます。
3. ユーザーによる確認。 クライアントがMCPエリシテーションに対応している場合（Claude Codeは対応しています）、サーバーは「『React Docs』にfrontendタグを追加しますか？」のように、変更内容を正確に説明するダイアログを表示し、承認された場合のみ書き込みます。クライアントがそのダイアログを表示できない場合、結果には"gate": "client"が含まれ、クライアント独自のプロンプトだけが確認手段だったことをアシスタントに伝えられます。

確認の待機時間は最大10分です。save_pageの取得処理は承認された後にのみ実行されるため、拒否されたURLがリクエストされることはありません。

ツール

読み取り（常時）：

ツール	機能
search	タイトル、コンテンツ、切り抜きテキスト、メモ、タグを全文検索します。クエリが空の場合は、必要に応じてタグで絞り込み、最新のページを表示します。bookmarked: true を指定すると、読書ブックマークが付いたページのみを表示します。
get_page	ID または URL を指定して、1 ページの全情報を取得します。メタデータ、タグ、要約、コンテンツ、メモと色付きの切り抜き、ブックマーク、ファイルパス、画像パスが含まれます。
list_recent	最終更新日時が新しいページを表示します。bookmarked: true を指定すると、読書ブックマークが付いたページをブックマーク日時の新しい順に表示します。
list_tags	ページ数とともに、すべてのタグを表示します。

書き込み（--allow-write）：

ツール	機能
save_page	URL を新しいページとして保存します（content を渡さない場合は、記事を取得して抽出します）。任意の summary（1〜2 文）と tags を指定できます。ページを読んだ場合は、Markpin 組み込み AI がブラウザーから保存されたページに対してのみ動作するため、アシスタントは両方を指定するよう求められます。URL ごとにページは 1 つで、既存のページがある場合は変更せずに返します。
update_tags	1 つ以上のページにタグを追加または削除します。
add_clip	ページに引用テキストの切り抜きを追加します。任意でメモ、ハイライトの color（amber、green、blue、pink）、リアクションマークの kind（question、insight、disagree、star）を指定できます。
set_clip_note	切り抜きのメモを置き換えます（空の場合はクリアします）。
set_summary	ページの要約を置き換えます（空の場合はクリアします）。要約なしで保存したページに便利です。
set_note	ページに読み手自身の 1 行メモを設定します（frontmatter の note。空の場合はクリアします）。
mark_skimmed	ページを流し読み済みとしてマークします（skimmedAt）。ブックマークと既読マークは削除されます。
delete_pages	ページを削除済みとしてマークします。Markpin 拡張機能は 30 日間保持し、復元できます。このサーバーがファイルを削除することはありません。
restore_pages	過去 30 日以内に削除されたページを復元します。
set_bookmark	ページに読書ブックマークを設定します。最初から再開するか、コンテンツ内の quote の位置から再開できます。既存のブックマークは置き換えられ、既読マークはクリアされます。
clear_bookmark	ページを既読としてマークせずに、ブックマークを削除します。
mark_read	ページを既読としてマークし、ブックマークを削除します。

書き込みのたびに note と gate フィールドが返されます（ダイアログで確認した場合は "elicitation"、アシスタントによる書き込みを妨げていたのがクライアントのプロンプトだけだった場合は "client"）。update_tags、set_clip_note、set_summary、set_note は before／after も返します。それ以外のツールは、影響を受けたページを返します。

制限事項

• Google Drive と新規ページ。 Google Drive ストレージでは、拡張機能が読み取れるのは自身が作成したファイルのみ（drive.file スコープ）です。そのため、save_page は Markpin フォルダー内の inbox.jsonl に新規ページを書き込み、拡張機能が次回の同期時にページファイルへ変換します。このファイルは拡張機能が作成して管理するため、削除しないでください。既存ページへの編集はその場で書き込まれます。ローカルフォルダーの場合、通常 inbox はなく、すべてが直接書き込まれます。フォルダー内に inbox.jsonl がある場合（たとえば、以前 Google Drive と同期していたフォルダーなど）は、サーバーは同じ方法で使用します。
• 領域切り抜きには非対応。 画像や領域の切り抜きにはページの DOM が必要です。サーバーが追加できるのはテキストの切り抜きのみです。
• サイドパネルの反映遅延。 サイドパネルを開いている間は 15 秒ごとにポーリングするため、変更が表示されるまで最大約 30 秒かかります。閉じている場合は、開いた時点で変更が表示されます。完全同期も 5 分ごとに実行されます。Google Drive の場合は、Drive for Desktop によるアップロードにかかる時間も加わります。
• 同時編集。 サーバーが読み取った後に拡張機能が同じページを書き換えた場合、書き込みは拒否され、Page changed on disk since it was read; re-read it and try again と表示されます。もう一度依頼してください。
• 削除記録。 削除済みページを完全に消去できるのは拡張機能だけです。このサーバーのみで使用するフォルダーでは、削除済みページは保持されます。

トラブルシューティング

症状	原因／対処方法
Not a directory: …	--dir の入力ミス、または Drive for Desktop が起動していない／フォルダーがミラーリングされていません。まず Finder または Explorer でパスを開いてください。
serving 0 pages	フォルダーに pages/ がまだないか、空です。Chrome でページを保存してください。Drive を使っている場合は、アップロードが完了するまで待ってください。
クライアントにサーバーの起動失敗と表示される	node -v を実行してください（20.1 以降が必要です）。Windows では cmd /c npx 形式を使用してください。エラーを確認するには、ターミナルで npx の行を実行してください。
たった今保存したページが表示されない	サーバーはファイルの変更から約 300 ms 後に再スキャンします。Drive を使っている場合、Drive for Desktop の同期が完了するとファイルが表示されます。
アシスタントが保存したページがサイドパネルに表示されない	サイドパネルを約 30 秒間開いたままにしてください。Google Drive を使っている場合、inbox.jsonl が Drive に届くよう、Drive for Desktop を起動しておく必要があります。
Chrome 拡張機能の更新後、ページが見つからない	ファイルは形式 v2 で書き込まれるようになりました（ファイル形式を参照）。0.7.0 より前のサーバーでは読み飛ばされます — npx -y @markpin/mcp@latest を実行するか、現在のバージョンで再登録してください。
書き込みツールが見つからない	--allow-write を指定せずに登録しています。再登録してからクライアントを再起動し、サーバーをもう一度起動してください。
アシスタントが保存したページに要約やタグがない	アシスタントはページを読まずに保存しました。要約とタグを作成するよう依頼してください（set_summary、update_tags）。
Not an HTML page／サーバーが URL を取得できない	サイトがボットをブロックしているか、ログインが必要です。アシスタント自身にページを読み取らせ、content を save_page に渡してください。
User declined／No response to the confirmation	ダイアログで拒否したか、10 分後にタイムアウトしました。何も書き込まれていません。

開発

yarn build:mcp                 # bundles to mcp-server/dist/index.js
node mcp-server/dist/index.js --dir "<dir>"

ライセンス：MIT。