markdown-notes-mcp

---

ライセンス： 個人の非営利目的であれば無料でご利用いただけます。LICENSE.md をご覧ください。

機能

AI アシスタントはプレーンテキストを読み取れ、一部は PDF も読み取れます。しかし、EPUB、OpenDocument、PowerPoint、スキャン画像を読み取れるものはなく、いずれもファイルをサーバーにアップロードして処理します。

このツールはお使いのマシン上でドキュメントを変換し、モデルが読みやすいように整えた Markdown を返します。表は Markdown の表に変換され、深いインデントは平坦化され、コードは適切なコードフェンスで囲まれます。

ドキュメント	PDF、Word .docx、Excel .xlsx/.xls/.xlsm、PowerPoint .pptx、OpenDocument .odt/.ods、EPUB、CSV、TSV、プレーンテキスト
画像	キーもネットワーク接続も不要な、デバイス上での OCR
音声	文字起こし — ローカルで実行できない唯一の機能

ツール

ツール	機能
convert_to_markdown	1 つのファイルを変換し、元のファイルと同じ場所に .md として自動保存します
convert_folder_to_markdown	複数のファイルを指定したディレクトリに変換します
save_summary	アシスタントが作成した要約を、ドキュメントと同じ場所に <name>.summary.md として保存します
list_supported_formats	拡張子と、設定されているオプションのクラウド機能を一覧表示します

トークンについて

変換に費用はかかりません。すべてローカルで実行されます。ただし、長いドキュメントを会話に返すと、手動で貼り付ける場合と同じレートでトークンを消費します。

そのため、長いドキュメントはディスクに保存し、短いプレビューのみを返します。50 ページの PDF なら、約 30,000 トークンではなく約 400 トークンで済みます。短いドキュメントは、どちらの方法でもコストが低いため、全文を返します。return_content: "full" を指定すると、この動作を変更できます。

インストール

Claude Desktop — 簡単な方法

Releases から .mcpb ファイルをダウンロードし、ダブルクリックします。Claude Desktop がインストールを行い、読み取りを許可するフォルダーと、必要に応じて API キーを尋ねます。Node もターミナルも JSON も不要です。

Claude Desktop — ソースから

npm install
npm run build
node scripts/install-claude-desktop.mjs --roots "D:\your\documents"

その後、Claude Desktop を完全に終了して再起動してください。このスクリプトは既存の設定を置き換えずに更新し、先にタイムスタンプ付きのバックアップを作成します。

--roots は省略可能ですが、指定をおすすめします。MCP サーバーが読み取れるフォルダーを制限できます。指定しない場合、アシスタントが要求したパスはすべて許可されます。

削除するには、次を実行します：node scripts/install-claude-desktop.mjs --remove

npm から — あらゆる MCP ホスト

npm install -g suprasuta-markdown-mcp

その後、ホストから suprasuta-markdown-mcp コマンドを指定するか、インストールせずに実行します。

{
  "servers": {
    "suprasuta-markdown": {
      "command": "npx",
      "args": ["-y", "suprasuta-markdown-mcp"],
      "env": { "MARKDOWN_MCP_ROOTS": "D:\\your\\documents" }
    }
  }
}

VS Code と Antigravity

どちらも標準の MCP 設定を読み取るため、上記の設定ブロックをそのまま使用できます。Antigravity は ~/.gemini/config/mcp_config.json、またはワークスペース内の .agents/mcp_config.json を参照します。

公開済みパッケージではなくチェックアウトしたソースを実行するには、command と args を node および dist/server.js の絶対パスに置き換えます。

オプションのクラウド機能

どちらもキーが設定されるまで無効です。それ以外の機能は、どちらも不要で動作します。

変数	有効になる機能	マシンから送信されるデータ
GEMINI_API_KEY	クラウド OCR。チャートや図の説明にも対応します	Google に送信される画像
ASSEMBLYAI_API_KEY	音声の文字起こし	AssemblyAI に送信される音声ファイル

キーは環境から読み込まれ、ディスクに書き込まれたり、ログに記録されたりすることはありません。

設定は起動時に一度だけ読み込まれます。 MCP サーバーは長時間実行されるプロセスのため、実行中に保存したキーやフォルダーの設定は、ホストを再起動するまで反映されません。入力したばかりのキーが未設定と表示される場合は、それ以上複雑な原因を探す前にホストを再起動してください。

開発

npm install          # .npmrc sets include=dev — do not delete it
npm run build        # stages the OCR engine, then bundles with esbuild
npm test             # 19 tests against the built bundle
npm run smoke        # converts every file in samples/ and reports
npm run typecheck

ビルドに tsc ではなく esbuild を使う理由

src/lib/convert/ は、Windows、Web、Android アプリ内のコピーとバイト単位で完全に同一に保たれているため、差異を後から発見するのではなく、検出できます。これらのファイルでは拡張子のないインポートと、Vite 固有の ?url インポートを使用していますが、どちらも Node 自身のリゾルバーでは受け付けられません。esbuild は両方を解決できるため、共有ファイルを Node に合わせて変更する必要がありません。

ランタイムフック

ブラウザーと Node で実際に異なる点は3つあり、src/lib/convert/runtime.ts は process の有無を調べるのではなく、ホストに問い合わせます。

フック	理由
tesseractPaths	ブラウザーには URL と専用のワーカーが必要です。Node にはファイルシステムのパスが必要で、ブラウザー用ワーカーを渡してはいけません
docxSource	mammoth はブラウザーでは arrayBuffer を、Node では buffer を読み取ります
ocrImageInput	tesseract の Node 版は Blob をデコードできず、Buffer を必要とします

それ以外はすべて共有されています。src/runtime/node.ts が Node 用の値を提供し、ブラウザーのグローバルである DOMParser だけをシムで補います。

苦い経験から学んだ注意点です。このファイルでは以前、document も定義していましたが、それが OCR を壊しました。tesseract.js は DOM を検出するとブラウザー用の処理に進み、window is not defined というエラーで失敗しました。中途半端なブラウザー環境は、何もないより悪いものです。シムは必要最小限にしてください。

コピーの整合性を保つ

npm run sync:check              # list differences against all three apps
npm run sync:pull web           # bring the web app's version in
node scripts/sync-converters.mjs --push web

このパッケージが正式なコピーです。両方の環境で同一ファイルを実行できるランタイムフックを備えているのはこのパッケージだけなので、修正はここから始め、ほかへ反映します。sync:check は差異を報告し、終了コード0で終了します。差異は情報であり、ビルドの失敗ではありません。

プライバシーポリシー

このソフトウェアは何も収集しません。アカウントも、分析も、テレメトリーも、独自のサーバーもありません。ドキュメントの変換はすべてお使いのマシン上で行われます。

任意の機能が2つあり、ご自身の API キーを入力した場合にのみ、サードパーティにデータを送信します。クラウド画像認識では画像を Google に送信し、音声の文字起こしでは音声を AssemblyAI に送信します。キーが設定されていなければ、このソフトウェアはネットワーク接続を一切行いません。API キーは環境から読み込まれ、ディスクに書き込まれることも、ログに記録されることもありません。

収集、保存、保持、第三者との共有、連絡先情報を網羅したポリシー全文：PRIVACY.md。

関連リンク

Windows アプリ	Microsoft Store · ソースコード
Web アプリ	markdown-notes-psi.vercel.app · ソースコード
Android	Chrome から Web アプリをインストール · 旧ネイティブ版（メンテナンス終了）