simplenote-mcp

simplenote-mcp

MCP（Model Context Protocol）対応のあらゆる AI ツールに Simplenote のデータへのアクセスを提供する MCP サーバーです。デフォルトでは読み取りのみで、書き込みモードを有効にして simplenote-mcp setup を実行すると、オプトイン方式の書き込みツール（作成、更新、ゴミ箱への移動、復元、巻き戻し）も利用できます。

macOS では、ローカルの Simplenote デスクトップアプリの Core Data ストアから直接読み取ることができます。完全にオフラインで、認証も不要です。Linux と Windows（およびデスクトップアプリのない macOS）では、一度だけ simplenote-mcp setup を実行したうえで、Simperium HTTP API と通信します。

Claude Desktop、Claude Code、Cursor、VS Code（Copilot）、Zed、Cline、Windsurf、その他 MCP に対応するあらゆるツールで動作します。

クイックスタート

セットアップを一度実行します:

npx -y @automattic/simplenote-mcp setup

Simplenote デスクトップアプリがインストールされ同期済みの macOS では、セットアップがローカルデータベースを検出し、それを使用するかどうかを尋ねます。このオプションを承諾すると、完全にオフラインかつ読み取り専用になります。Linux、Windows、またはデスクトップアプリのない macOS では、セットアップが Simplenote のメールアドレスを尋ね、認証コードを送信したうえで、コードと書き込みモードを有効にするかどうかを尋ねます。

次に、MCP クライアントにサーバーを登録します。

Claude Code:

claude mcp add simplenote -- npx -y @automattic/simplenote-mcp

Codex:

codex mcp add simplenote -- npx -y @automattic/simplenote-mcp

Claude Desktop、Cursor、VS Code、Zed、Cline、Windsurf については、以下の設定を参照してください。これらのクライアントは、CLI コマンドではなく JSON ファイルを編集して設定します。

クライアントを再起動し、タグの一覧を表示するよう依頼してください。

要件

• Node.js 22+
• 次のいずれか:
  • macOS: Simplenote デスクトップアプリがインストールされ、同期済みであること、または
  • 任意のプラットフォーム: Simplenote アカウント（simplenote-mcp setup を一度実行します）

インストール

ほとんどのユーザーは手動で何かをインストールする必要はありません。MCP 設定に npx -y @automattic/simplenote-mcp を記述すれば、初回使用時にインストールされます。

グローバルインストールを希望する場合（起動が速く、初回使用時にコールドキャッシュのダウンロードが発生しません）:

npm install -g @automattic/simplenote-mcp

その後、MCP 設定の command に simplenote-mcp を直接指定します。

セットアップと認証

config.json を作成するためにセットアップを一度実行します。ネイティブの macOS セットアップでは Simplenote の認証は不要ですが、API セットアップでは必要です。

一度だけのセットアップ

npx -y @automattic/simplenote-mcp setup

ローカルの macOS Simplenote データベースが検出された場合、セットアップはそれを使用することを提案し、source: "local" を指定した config.json を書き込みます。

そうでない場合、セットアップは auth.json に既存のトークンがあるか確認します。すでに保存されていれば、セットアップはそれを再利用し、書き込みモードを有効にするかどうかだけを尋ねます。トークンが保存されていない場合、セットアップは Simplenote のメールアドレスを尋ね、短い認証コードを含むマジックリンクのメールを送信し、そのコードを尋ねたうえで、書き込みモードを有効にするかどうかを尋ねます。成功すると、config.json を書き込み、トークンをモード 0600 で auth.json に保存します。

プラットフォーム	パス
macOS	~/Library/Application Support/simplenote-mcp/auth.json
Linux	$XDG_CONFIG_HOME/simplenote-mcp/auth.json（デフォルトは ~/.config/simplenote-mcp/auth.json）
Windows	%APPDATA%\simplenote-mcp\auth.json

config.json と telemetry.json は同じ simplenote-mcp 設定ディレクトリにあります。

保存されたトークンを削除するには:

npx -y @automattic/simplenote-mcp logout

ヘッドレス / CI

トークンを直接エクスポートすることで auth.json をスキップします:

SIMPLENOTE_TOKEN=<token> npx -y @automattic/simplenote-mcp

この環境変数は auth.json をバイパスします。

SIMPLENOTE_TOKEN は config.json をバイパスしません。ローカルストアと API プロバイダーのどちらを使用するかを知るために、サーバーは依然として設定を必要とします。ヘッドレス環境では、上記のプラットフォーム固有の設定ディレクトリと同じ場所に config.json を作成します:

{
  "source": "api",
  "writeMode": false
}

writeMode は、書き込みツールを公開したい場合にのみ true に設定します。

トークンの有効期間

マジックリンクトークンはユーザーごとに固定されているように見えます (新しいコードをリクエストしても、サーバー側で無効化されるまで同じトークンが返されることがよくあります)。通常の使用では有効期限は確認されていません。Simperium API から 401 が返された場合は、「古いトークンを削除してセットアップを再実行する」ものとして扱ってください。自動更新はありません — マジックリンク認証にはユーザーの操作が必要です。認証エンドポイントにはレート制限があり (繰り返し失敗すると IP が約 10 分間ロックアウトされます)、繰り返し試行をスクリプト化しないでください。

設定

CLI を備えたクライアント (Claude Code、Codex) では、1 つのコマンドでサーバーを登録できます — 以下を参照してください。それ以外はすべて JSON です。すべての MCP クライアントは同じ { command, args, env } の形に収束しており、異なるのは設定ファイルの場所と最上位のキー (mcpServers 対 servers 対 context_servers) だけです。

Claude Code

推奨:

claude mcp add simplenote -- npx -y @automattic/simplenote-mcp

または、以下と同じ JSON の形で ~/.claude.json / プロジェクトの .mcp.json を編集します (Claude Desktop の場合と同様)。

Codex

推奨:

codex mcp add simplenote -- npx -y @automattic/simplenote-mcp

または、~/.codex/config.toml を直接編集します:

[mcp_servers.simplenote]
command = "npx"
args = ["-y", "@automattic/simplenote-mcp"]

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) または %APPDATA%\Claude\claude_desktop_config.json (Windows)。

{
  "mcpServers": {
    "simplenote": {
      "command": "npx",
      "args": ["-y", "@automattic/simplenote-mcp"]
    }
  }
}

クライアントを起動する前に、ターミナルで npx -y @automattic/simplenote-mcp setup を一度実行してください。

設定変更を反映するには Claude Desktop を再起動してください。Windows 固有の癖については、以下の Windows の注意事項 を参照してください。

Cursor

~/.cursor/mcp.json (グローバル) または .cursor/mcp.json (プロジェクトごと)。Claude Desktop と同じ JSON の形です。

VS Code (GitHub Copilot)

コマンドパレット → 「MCP: Open User Configuration」 でユーザー設定を開くか、プロジェクトごとに .vscode/mcp.json を使用します。注意: VS Code では最上位に mcpServers ではなく servers を使用します。

{
  "servers": {
    "simplenote": {
      "command": "npx",
      "args": ["-y", "@automattic/simplenote-mcp"]
    }
  }
}

Zed

Zed の settings.json で:

{
  "context_servers": {
    "simplenote": {
      "command": {
        "path": "npx",
        "args": ["-y", "@automattic/simplenote-mcp"]
      }
    }
  }
}

Zed は異なるスキーマを使用します — context_servers とネストされた command オブジェクトです。

Cline

Cline MCP Servers パネルを開く → cline_mcp_settings.json を編集します。Claude Desktop と同じ JSON の形です (mcpServers が最上位のキー)。

Windsurf

~/.codeium/windsurf/mcp_config.json。Claude Desktop と同じ JSON の形です。

カスタムストアパス (macOS)

ローカルの Simplenote データがデフォルトのパスにない場合:

1. Finder を開き、Cmd+Shift+G を押して ~/Library/Group Containers/ を貼り付けます
2. com.automattic.SimplenoteMac で始まるフォルダーを探します (通常は PZYM8XX95Q. のようなプレフィックスが付きます)
3. Data/Simplenote.storedata に移動します

次に --path を渡します:

{
  "mcpServers": {
    "simplenote": {
      "command": "npx",
      "args": [
        "-y",
        "@automattic/simplenote-mcp",
        "--path",
        "/path/to/Simplenote.storedata"
      ]
    }
  }
}

--path は、トークンが設定されていても、常にネイティブプロバイダーを強制します。

その他のフラグ

• -h、--help — 使用方法を表示して終了します。
• -V、--version — バージョンを表示して終了します。

不明なフラグや予期しない位置引数は拒否されます。これにより、--paht のような単純なタイプミスが無視され、config.json で設定されたプロバイダーにフォールバックすることを防ぎます。

テレメトリー

Simplenote MCP は匿名の使用状況イベントを Automattic に送信します。ランダムな UUID が config.json と同じ設定ディレクトリ内の telemetry.json に保存され、_ui として _ut=simplenote:local_uuid とともに送信されます。

追跡されるイベントは、セットアップの選択 (type、OS ファミリー、書き込みモード、API セットアップの認証方法) とツール呼び出し (tool、プロバイダー、成功/失敗) に限定されています。ノート ID、ノートの内容、タグ、検索クエリ、Simplenote アカウントの詳細、トークンは決して送信されません。

1 回の実行でオプトアウトするには、次を設定します:

SIMPLENOTE_MCP_DISABLE_TELEMETRY=1 npx -y @automattic/simplenote-mcp

永続的にオプトアウトするには:

npx @automattic/simplenote-mcp disable-telemetry

ビルド後にローカルのチェックアウトから実行する場合、node server.js disable-telemetry も使用できます。

プロバイダーの解決

サーバーは --path が指定されている場合を除き、config.json からデータソースを選択します。

1. --path <file> — 指定されたストアファイルに対してネイティブ macOS プロバイダーを強制します
2. source: "local" — デフォルトの macOS Simplenote ストアを読み取り専用で使用します
3. source: "api" と auth.json または SIMPLENOTE_TOKEN — Simperium API プロバイダーを使用します
4. 設定が存在しないか不正な場合 — 対処方法を示す simplenote-mcp setup メッセージを表示して終了します

設定を作成または置き換えるには simplenote-mcp setup を実行してください。トークンだけでは API プロバイダーを選択するのに十分ではありません。

利用可能なツール

基本的な読み取りツールは、設定されたプロバイダーにかかわらず利用できます。ネイティブ macOS モードはローカルかつ読み取り専用です。書き込みツールとバージョン履歴ツールには Simperium API プロバイダーが必要です。現在のサーバーでは、API 書き込みモードが有効な場合に公開されます。

list_tags

Simplenote アカウント内のすべてのタグを一覧表示します。

パラメーター: なし

戻り値: index でソートされた {name, index} の配列

list_notes

最近のノートを一覧表示します。オプションでタグによる絞り込みが可能です。

パラメーター:

• tag (文字列, 任意) — タグ名で絞り込み
• limit (数値, 任意, デフォルト: 20, 最大: 100) — 返すノートの最大数
• include_deleted (真偽値, 任意, デフォルト: false) — ゴミ箱内のノートを含める

戻り値: ピン留め状態、次に更新日時でソートされた {id, title, tags, pinned, modified, deleted} の配列

search_notes

内容、タイトル、またはタグでノートを検索します。

パラメーター:

• query (文字列, 必須) — 検索語 (大文字と小文字を区別しません)
• limit (数値, 任意, デフォルト: 10, 最大: 100) — 結果の最大数
• include_deleted (真偽値, 任意, デフォルト: false) — 削除済みノートを含める

戻り値: {id, title, tags, snippet, modified, deleted} の配列

get_note

特定のノートの完全な内容を取得します。

パラメーター:

• id (文字列, 必須) — ノート ID (simperiumkey)
• include_deleted (真偽値, 任意, デフォルト: false) — 削除済みノートの取得を許可する

戻り値: {id, content, tags, pinned, markdown, deleted, created, modified}

create_note

新しいノートを作成します。書き込みツール — simplenote-mcp setup で書き込みモードが有効になっており、Simperium API プロバイダーが必要です。

パラメーター:

• content (文字列, 必須) — ノートの内容 (最初の行がタイトルになります)
• tags (文字列の配列, 任意) — 付与するタグ
• markdown (真偽値, 任意, デフォルト: true) — markdown レンダリングを有効にする
• pinned (真偽値, 任意, デフォルト: false) — リストの先頭にピン留めする

戻り値: {success, id, version, title}

update_note

既存のノートを更新します。書き込みツール — 書き込みモードと Simperium API プロバイダーが必要です。

重要: content と tags は既存の値を完全に置き換えます。ノートの一部のみを変更する場合は、まず get_note を呼び出し、マージした内容を渡し直してください。部分的な値を渡すと残りが消去されます。

パラメーター:

• id (文字列, 必須) — ノート ID
• content (文字列, 任意) — 新しいノートの内容
• tags (文字列の配列, 任意) — タグリストを置き換える (完全なリストを指定してください)
• markdown (真偽値, 任意) — markdown レンダリングを有効/無効にする
• pinned (真偽値, 任意) — ピン留め/ピン留め解除

content、tags、markdown、または pinned のうち少なくとも 1 つを指定する必要があります。

戻り値: {success, id, version}

trash_note

ノートをソフト削除します (Simplenote のゴミ箱に移動します)。ノートはバケット内に残り、任意の Simplenote クライアントから復元できます。書き込みツール — 書き込みモードと Simperium API プロバイダーが必要です。

パラメーター:

• id (文字列, 必須) — ノート ID

戻り値: {success, id, title, trashed_at}

restore_note

以前にゴミ箱へ移動したノートを復元し、アクティブなリストに再表示させます。trash_note の逆の操作です。書き込みツール — 書き込みモードと Simperium API プロバイダーが必要です。

パラメーター:

• id (文字列, 必須) — ノート ID

戻り値: {success, id, title, restored_at}

get_note_history

ノートの最近のバージョンを、短いコンテンツプレビュー付きで一覧表示します。読み取り専用操作です。現在のサーバーで書き込みモードが有効な Simperium API プロバイダーが必要です。

パラメータ:

• id (string, 必須) — ノート ID
• limit (number, 任意, デフォルト: 10, 最大: 25) — 返すバージョンの最大数

戻り値: {id, current_version, entries: [{version, modified_at, content_preview}]} を最新順で返します。Simperium の保持期間外のバージョンは通知なく破棄されます。連続していない version 番号は、その欠落を示します。

get_note_version

ノートの特定の過去バージョンの完全なコンテンツを取得します。読み取り専用操作です。現在のサーバーで書き込みモードが有効な Simperium API プロバイダーが必要です。revert_note を呼び出す前にコンテンツをプレビューするために使用します。

パラメータ:

• id (string, 必須) — ノート ID
• version (number, 必須) — バージョン番号 (正の整数)

戻り値: {id, version, content, tags, pinned, markdown, deleted, created, modified}。バージョンが Simperium の保持期間外の場合、version_not_found をスローします。

revert_note

ノートを以前のバージョンに復元します。書き込みレートの予算にカウントされます。ゴミ箱に入れられたノートのガードをバイパスします。ゴミ箱に入っていないバージョンに復元するとゴミ箱から戻り、ゴミ箱に入れられたバージョンに復元すると再度ゴミ箱に入ります。

推奨フロー: get_note_history → get_note_version (プレビュー用) → revert_note。

パラメータ:

• id (string, 必須) — ノート ID
• version (number, 必須) — 復元する対象バージョン (正の整数)

戻り値: {success, id, reverted_from_version, new_version, no_op}。no_op: true は、対象バージョンが現在のバージョンと同一だったことを意味します。書き込みは行われず、レート予算も消費されません。

simplenote-mcp setup で書き込みモードを有効にする必要があります。保持期間は Simperium によって決定され、クライアント側からは設定できません。

使用例

設定が完了すると、AI クライアントに次のように尋ねることができます:

• 「Simplenote のタグを一覧表示して」
• 「最近のノートを見せて」
• 「ノートから『レシピ』を検索して」
• 「『アイデア』タグが付いたノートを見せて」
• 「ノート [id] の完全なコンテンツを取得して」
• 「[ノートタイトル] のバージョン履歴を見せて」
• 「そのノートのバージョン 42 がどうだったか見せて」
• 「そのノートを前のバージョンに戻して」

書き込みツール (作成、更新、ゴミ箱、復元、リバート) はデフォルトで無効になっており、Simperium API プロバイダーでのみ利用できます。simplenote-mcp setup を実行してオプトインすると有効になります。ネイティブの macOS データはメモリにキャッシュされ、ストアファイルが変更されると更新されます。Simperium API の応答は 60 秒間キャッシュされ、API に一時的に到達できない場合は古いキャッシュにフォールバックします。

Windows に関する注意

知っておく価値のある、Windows 固有のいくつかの癖:

• Claude Desktop では npx を cmd /c でラップしてください。そうしないと、子プロセスランチャーが PATH 上の npx.cmd を見つけられないことがあります:

  {
    "mcpServers": {
      "simplenote": {
        "command": "cmd",
        "args": ["/c", "npx", "-y", "@automattic/simplenote-mcp"]
      }
    }
  }
  

• Claude Desktop の %APPDATA% 展開は、一部のバージョンで通知なく失敗することがあります。サーバーが設定ディレクトリを見つけられない場合は、env ブロックで APPDATA を明示的に設定してください:

  "env": {
    "APPDATA": "C:\\Users\\<you>\\AppData\\Roaming"
  }
  

• バックスラッシュを含むパスは JSON 内でエスケープする必要があります ("C:\\Users\\...")。フォワードスラッシュも使用でき ("C:/Users/...")、エラーが発生しにくくなります。

トラブルシューティング

「No configuration found. Run simplenote-mcp setup...」 MCP クライアントを起動する前に、npx -y @automattic/simplenote-mcp setup を一度実行してください。

「Not logged in. Run simplenote-mcp setup...」 トークンなしで Simperium API のパスを使用しています。ターミナルで npx -y @automattic/simplenote-mcp setup を実行してください。

「Token rejected.」 トークンがサーバー側で無効化された可能性があります。npx -y @automattic/simplenote-mcp logout を実行してから、npx -y @automattic/simplenote-mcp setup を実行してください。

ツール一覧が空 / 「Simplenote store not found」 macOS ではデフォルトのパスは ~/Library/Group Containers/PZYM8XX95Q.com.automattic.SimplenoteMac/Data/Simplenote.storedata です。ストアが別の場所にある場合は、--path を渡してください。デスクトップアプリがない場合は、simplenote-mcp setup で API パスに切り替えてください。

最初のツール呼び出しが非常に遅い npx -y は初回使用時にパッケージをダウンロードします。低速なネットワークでは、MCP クライアントの起動タイムアウト（約 10 秒）を超えることがあります。ウォームアップを待つか、一度グローバルにインストールしてください: npm install -g @automattic/simplenote-mcp を実行し、"command": "npx" を "command": "simplenote-mcp" に変更します（args は削除します）。

Windows で「command not found: npx」/「spawn npx ENOENT」 Windows notes の cmd /c ラッピングを参照してください。

セットアップメールが届かない 迷惑メールフォルダを確認してください。認証エンドポイントにはレート制限があり、短時間に複数回失敗すると IP が約 10 分間ロックアウトされます。待ってから再試行してください。

すべて正常に見えるがデータが古いようだ Simperium のレスポンスは 60 秒間キャッシュされます。ネイティブの macOS プロバイダーは、ストアファイルの mtime が変更されると更新されます。1 分待つか、MCP クライアントを再起動して再取得を強制してください。

開発

ソースは src/ にあり、コンパイル済みの出力は dist/ にあります。

git clone https://github.com/Automattic/simplenote-mcp.git
cd simplenote-mcp
npm install          # installs deps + builds via `prepare`
npm test             # runs the test suite
npm run typecheck    # tsc --noEmit
npm run build        # tsc + chmod +x on the bin

MCP Inspector を使用したローカルでのテスト

MCP Inspector は、MCP サーバー用のブラウザ UI を提供します。サーバーが公開するツール、プロンプト、リソースを一覧表示し、任意の引数でそれらを呼び出せます。また、双方向の生の JSON-RPC を出力します。サーバーを実際のクライアントに組み込むことなくコード変更を試したいときに便利です。

ローカルビルドに対して実行:

npm run build
npm run inspect

出力された URL を開き、Connect をクリックします。

再ビルドせずにソースから実行（最速のイテレーション — tsx を使用）:

npx @modelcontextprotocol/inspector npx tsx src/server.ts

公開されている npm パッケージをテスト（ユーザーが実際に入手するものと同一）:

npx @modelcontextprotocol/inspector npx -y @automattic/simplenote-mcp

プロバイダーを明示的に指定:

• カスタムストアに対してネイティブの macOS プロバイダーを強制（設定を上書き）:

  npx @modelcontextprotocol/inspector node dist/server.js --path /path/to/Simplenote.storedata
  

• Simperium API プロバイダーを使用 — 事前に API モードを選択して simplenote-mcp setup を実行している必要があります。これにより、source: 'api' と auth.json トークンを含む設定が書き込まれます。その後、Inspector は自動的に API プロバイダーを選択します。セッションで別のトークンを使用するには、Inspector を起動する前に SIMPLENOTE_TOKEN をエクスポートするか（auth.json を上書き）、Inspector UI の Environment Variables パネルに貼り付けます。

Inspector は stdio 経由でサーバーをサブプロセスとして起動するため、実際の MCP クライアント設定で動作するものはすべてここでも動作します — --path、環境変数、代替の Node バイナリなどが含まれます。

Claude Code を使用したローカルでのテスト

このリポジトリには、プロジェクトスコープの .mcp.json が含まれており、ローカルのソースを simplenote-dev という名前のサーバーとして登録します。リポジトリのディレクトリで Claude Code を開くと、そのサーバーを有効化するかどうかを確認されます（ファイルがコミットされているため、初回は権限を求められます）。有効化すると、このディレクトリでの Claude Code セッションは node --import tsx src/server.ts を介して開発中のコードと通信します — ビルドステップは不要です。

ワークフロー:

1. tsx を利用できるように npm install を実行し、まだの場合は simplenote-mcp setup を一度実行してください。開発サーバーは通常のインストールと同じ config.json/auth.json を読み取ります。
2. リポジトリのディレクトリで Claude Code を開き、確認されたら simplenote-dev を承認します。
3. src/ を編集して保存し、Claude Code で /mcp を実行して simplenote-dev を再接続すると変更が反映されます。

プロジェクトスコープとは、開発サーバーがこのディレクトリでのみアタッチされることを意味します — マシン上の他の場所にある Claude Code セッションを汚染しません。

注意: config.json に writeMode: true が設定されている場合、開発サーバーは実際の Simplenote ノートを変更します — 開発データと本番データの間に分離はありません。イテレーション中は書き込みモードを無効にしてセットアップを実行するか、使い捨ての Simplenote アカウントでテストしてください。

リポジトリのルートにある server.js は dist/server.js をインポートする薄いシムであり、npm パッケージが存在する前にローカルクローンを指す設定を行っていたユーザーのために安定した状態で維持されています。

ライセンス

MIT