mcp-warden

mcp-warden

Model Context Protocol 用のローカル優先の認証情報ブローカーです。Claude Code、Cursor、Cline、Codex、Continue、Zed などの AI コーディングエージェントが、シークレットを一切見ることなく実際の操作を行えるようにします。

エージェントは高レベルのツール（proxy_http）を呼び出し、mcp-warden がサーバー側でシークレットを注入して操作を実行し、結果のみを返します。コンテキストウィンドウはクリーンなままです。会話ログが漏れても、有用な情報は何も漏れません。

仕組み

1. mcp-warden CLI を使って、認証情報を OS のキーチェーンに一度だけ保存します。
2. 名前とスコープを設定したアクション（例：github-read、stripe-charges）であるプリセットを定義します。
3. AI エージェントは MCP サーバー（stdio）として mcp-warden に接続します。
4. エージェントが操作を実行するときは、プリセット名とパス／メソッドを指定して proxy_http を呼び出します。
5. mcp-warden はプリセットの許可リストに照らしてリクエストを検証し、認証情報を注入して実行し、レスポンスのみを返します。
6. 機密性の高いプリセットでは、承認プロンプトが表示されます。macOS と Windows ではネイティブダイアログ、Linux では「承認／拒否」ボタン付きのデスクトップ通知、どの OS でも Telegram メッセージを利用できます。Telegram では、スマートフォンからのキルスイッチとして /lock も機能します。プリセットごとに時間制限付き承認を有効にすると、短時間に続く複数の呼び出しを 1 回の承認で許可でき、承認プロンプトの連発を避けられます。
7. すべての操作がローカルの SQLite 監査ログに記録されます。これには、有効な承認期間中に許可された呼び出しの windowed 判定、許可リストで拒否された呼び出しの refused 判定（要求されたパスまたはコマンドの生データを含む）、承認プロンプトを表示できなかった場合の failed 判定も含まれます。

エージェントのコンテキストウィンドウにシークレットは一切含まれません。

インストール

cargo install --locked mcp-warden # from crates.io
cargo install --locked --path .   # or from a clone

macOS（x86_64、aarch64）および Linux（x86_64）向けのビルド済みバイナリには、それぞれ SHA-256 チェックサムが付属しており、すべての GitHub リリースに添付されています。

90 秒で始めるクイックスタート

mcp-warden init
mcp-warden secret add gh_pat                  # paste your GitHub PAT when prompted
mcp-warden preset add github-read \
  --type http \
  --base-url https://api.github.com \
  --auth-bearer gh_pat \
  --allowed-methods GET \
  --allowed-paths /user/repos \
  --approval auto --confirm-auto

このプリセットが自動承認するのは GET /user/repos だけです。それ以外のパスは、トークンに触れる前に拒否されます。エージェントにほかの情報も読み取らせるには、許可リストを広げ（例：--allowed-paths '/user/repos,/repos/OWNER/[^/]+'）、特定のリポジトリに限定した細粒度の PAT を使用してください。パターンはパス全体に一致する必要があり、完全一致または ^(?:…)$ でアンカーされた正規表現として扱われます。プレフィックスとしては扱われません。1 セグメントには .* より [^/]+ のほうが安全です。パスはパーセントデコードされてから照合されるため、%2F は区切り文字です。したがって、GitLab 形式の ID（例：/projects/group%2Fproject）には /projects/[^/]+/[^/]+ が必要です。allowed_paths が設定されていない HTTP プリセットでは、base_url 配下のすべてのパスが許可されます。preset add と doctor はこの点を警告し、組み込みの github-read／gitea-read／stripe-read テンプレートでは、そのため approval = "prompt" が設定されています。

docs/claude-code-setup.md または docs/cursor-setup.md を参照して、mcp-warden をエージェントに接続してください。

エージェントに「mcp-warden 経由で GitHub のリポジトリを一覧表示して」と頼んでみましょう。エージェントが list_presets、続いて proxy_http を呼び出す様子を確認してください。そして、PAT がプロンプトに含まれないことも確認できます。

mcp-warden audit --last 5                     # see what the agent did

平文のキーを見つけて修正する

MCP クライアントの設定に貼り付けたキーは、ディスク上に平文で保存されるため、エージェント、同期されたドットファイル、スクリーンショットから読み取られる可能性があります。次の3つのコマンドで修正できます：

mcp-warden scan                     # where are plaintext keys? (shows type + length, never values)
mcp-warden import                   # move them into the keychain and rewire the client entries
mcp-warden run github               # what the rewired entry runs: the server, with its key injected

scan は、Claude Code、Claude Desktop、Cursor、Windsurf、VS Code、Codex の設定に加え、現在のディレクトリにある .mcp.json / .env ファイルを読み取ります（さらに検索するには --path DIR を指定します）。import は、stdio サーバーの env にあるキーを処理します。引数、ヘッダー、URL、.env ファイルにあるキーについては、代わりに何をすべきかを scan が示します。サーバーを手動でラップするには、mcp-warden server add github --env GITHUB_PERSONAL_ACCESS_TOKEN -- npx -y @modelcontextprotocol/server-github を実行します（値は標準入力から読み取られます）。詳しくは docs/scan-and-import.md をご覧ください。

CLI リファレンス

コマンド	説明
mcp-warden init	設定ディレクトリと設定テンプレートを作成します
mcp-warden secret add <name>	シークレットを保存します（値は標準入力から読み取り、argv には渡しません）
mcp-warden secret list	シークレット名を一覧表示します（値は表示しません）
mcp-warden secret remove <name>	キーチェーンからシークレットを削除します
mcp-warden preset add <name> ...	プリセットを定義します（auto には --confirm-auto が必要です）
mcp-warden preset list	すべてのプリセットを表示します
mcp-warden preset test <name>	現在のキーチェーンに照らしてプリセットを検証します
mcp-warden preset test <name> GET /path	ポリシーシミュレーター：この呼び出しは許可されるか、その理由は何かを確認します。何も送信しません（他のツールでは --command、--get/--put、--query を使用）
mcp-warden preset grant <name> --for 1h	時間制限付きアクセスを許可します。期間終了後は呼び出しが拒否されます（--permanent で解除します）
mcp-warden preset revoke <name>	プリセットへのアクセスを終了します（次回のサーバー起動時に反映。即時に反映するには lock を使用）
mcp-warden lock [--reason …]	キルスイッチ：次回以降、すべての MCP サーバーがすべての呼び出しを拒否します（または Telegram ボットに /lock を送信します）
mcp-warden approval telegram-test	Telegram の設定を確認します：トークン、チャット、回答するテストプロンプト
mcp-warden unlock	ダイアログ / Telegram で人間が承認した後にロックを解除します
mcp-warden scan	MCP クライアント設定と .env ファイル内の平文キーを探します（値は表示しません）
mcp-warden import	scan で見つかったキーをキーチェーンに移し、クライアントが mcp-warden run を参照するようにします
mcp-warden server add <name> --env VAR -- <cmd…>	別の MCP サーバーをラップします。そのキーは標準入力からキーチェーンに読み込まれます
mcp-warden run <name>	キーを注入してラップ済み MCP サーバーを起動します（クライアントのコマンドとして使用します）
mcp-warden preset scaffold <template> (v0.3.0)	組み込みテンプレートからプリセットを生成します（利用可能なテンプレートを確認するには --list を指定）
mcp-warden preset from-openapi <src> (v0.3.0)	OpenAPI 3.x 仕様（URL またはファイル）からプリセットを作成します
mcp-warden approval <preset> <policy> [--window N]	承認ポリシーを設定します。--window N（秒）を指定すると、prompt の承認に時間制限を設定できます
mcp-warden audit [--last N | --since T]	追記専用設計の監査ログを読み取り専用で表示します。拒否された呼び出しを含むエージェントの要求内容と、各呼び出しを行った MCP クライアントおよびセッションを確認できます
mcp-warden doctor [--deep] (v0.3.0 for --deep)	診断の概要を表示します。--deep はプリセットごとに安全な読み取り専用 HTTP プローブを実行します
mcp-warden web [--port N] (v0.3.0)	ローカルの読み取り専用 Web UI（127.0.0.1 のみにバインド）
mcp-warden mcp	stdio 経由で MCP サーバーを実行します（AI エージェントが使用）

公開されている MCP ツール

• list_presets — 利用可能なアクションの読み取り専用カタログです。
• proxy_http — プリセットを通じて HTTP リクエストを実行します。認証情報を挿入する前に、許可リストの検証を行います。
• ssh_exec (v0.2.0) — SSH ホスト上でシェルコマンドを実行します。コマンドは、プリセットのアンカー付き正規表現許可リストに一致する必要があります。鍵ベースの認証とホスト鍵の検証を使用します。
• sftp_transfer (v0.2.0) — SFTP 経由でファイルを取得または送信します。リモートパスはプリセットの sftp_allowed_paths に一致し、ローカルパスは $HOME または /tmp の配下である必要があります。
• db_query (v0.2.0) — PostgreSQL／MySQL／Redis に対して名前付きクエリを実行します。SQL／コマンドはプリセットの定義で固定され、エージェントが指定できるのは query_name と位置パラメーターのみです。
• get_secret_for_env — 子プロセスが env からシークレットを読み取る必要がある場合に使用する最終手段のツールです。プリセットのポリシーにかかわらず、必ず承認を求めます。

Claude Code プラグイン

Claude Code 用のプラグインには、MCP サーバーの設定、mcp-warden を正しく使う方法を Claude に教えるスキル（最初にプリセットを確認する、トークンを求めない、承認を尊重する、get_secret_for_env は最終手段として扱う）、およびガイド付きの /mcp-warden:setup コマンドが含まれています。まずバイナリをインストールし、その後 Claude Code で次を実行します。

/plugin marketplace add ermoluk/mcp-warden
/plugin install mcp-warden@mcp-warden

Claude Code を再起動し、/mcp-warden:setup を実行します。以前 claude mcp add でサーバーを追加していた場合は、二重に登録されないよう、そのエントリーを削除してください。詳細は plugins/mcp-warden/ を参照してください。

その他の MCP クライアントについては、手動でのセットアップ方法を docs/claude-code-setup.md と docs/cursor-setup.md で確認してください。

v0.5.1 の新機能

• cargo install mcp-warden が再びビルドできるようになりました。 keyring クレートのマイナーリリースで使用していた関数が削除されたため、0.5.0 は --locked を指定しないとコンパイルに失敗していました。mcp-warden は OS のキーチェーンストアと直接やり取りするようになり、以前のバージョンで保存したシークレットも引き続き読み取れます。cargo install --locked mcp-warden でインストールしてください。

v0.5.0 の新機能

• すべてのデスクトップで承認できます。 prompt プリセットは、macOS と Windows でネイティブダイアログを表示して確認するようになりました。デフォルトでは拒否され、Return／Esc キーでも拒否されます。また、60 秒後に自動的に拒否されます。0.4.x では、Telegram が設定されていない場合、MCP クライアント経由では macOS の prompt プリセットを承認できませんでした。プロンプトを表示できない場合は拒否され、failed として監査ログに記録されます。
• キルスイッチ。 mcp-warden lock を実行すると、実行中のすべての MCP サーバーが、次の呼び出し以降すべてを拒否します。一度ロックを認識したサーバーは、再起動するまでロックされたままです。mcp-warden unlock を実行するには、ダイアログまたは Telegram で承認する必要があります。Telegram が設定されていれば、スマートフォンから /lock を送信して同じ操作を行えます。
• 平文のキーを見つけて修正します。 mcp-warden scan は、MCP クライアントの設定ファイルや .env ファイルに貼り付けられた API キーを見つけますが、値を出力することはありません。mcp-warden import でキーをキーチェーンに移し、mcp-warden run <name> でキーを挿入した状態でサーバーを起動できます（平文のキーを見つけて修正するを参照）。
• アクセス期間の制限とポリシーシミュレーター。 preset grant <name> --for 1h と preset revoke <name> で、プリセットが有効な期間を制限できます。preset test <name> GET /path を実行すると、何も送信せずに、その呼び出しが許可されるかどうかと、その理由を確認できます。
• より厳格な応答処理。 上流サービスから返された認証情報は、エージェントに表示される前に削除されます。プリセットごとに、max_response_bytes で応答本文のサイズを制限し、response_fields で指定したフィールドだけを返せます。
• 監査ログの改善。 すべてのイベントに、それを発生させた MCP クライアントとセッションが記録されます。
• 複数セッションでの Telegram 利用。 複数の Claude セッションで 1 つのボットを共有できます。交代でポーリングするため、ボタン操作が取りこぼされなくなりました。mcp-warden approval telegram-test を実行すると、設定を最初から最後まで確認できます。
• テンプレートを 5 つ追加： gitlab-read、linear、jira-read、slack-read、vercel-read。
• 動作の変更点：
  • MCP サーバーは起動時に config.toml を一度だけ読み込むため、プリセットを編集した後は再起動してください。
  • Rust の最小バージョンが 1.89 になりました。

全変更の一覧：CHANGELOG.md。

v0.4.0 の新機能

• ワークスペースの分割。 プロジェクトは 2 つのクレートで構成されるようになりました。mcp-warden-core（ライブラリ — トレイトのインターフェースと共通型）と mcp-warden（バイナリ — CLI、MCP サーバー、エグゼキューター、ウェブ UI、具体的な承認トランスポート）です。KeychainStore、ApprovalTransport、AuditSink、PresetSource の代替実装は、mcp-warden-core のみに依存するようになり、バイナリの GUI／ランタイムスタックを引き込まなくなりました。
• Telegram 承認トランスポートに対応。 実装自体は v0.3.0 にすでに存在していましたが、v0.4.0 で実際に選択できるようになりました。設定ファイルに以下を追加してください（mcp-warden doctor を実行すると設定ファイルのパスが表示されます。Linux では ~/.config/mcp-warden/、macOS では ~/Library/Application Support/io.mcp-warden.mcp-warden/）：

  [approval.telegram]
  bot_token_secret = "tg_bot_token"   # name of the keychain entry, not the token value
  chat_id = 123456789                  # your numeric Telegram chat id
  timeout_seconds = 120                # optional
  

  次に mcp-warden secret add tg_bot_token を実行します（ボットトークンがキーチェーンに貼り付けられます）。prompt ポリシーのプリセットは、そのチャットにインラインボタン付きの承認／拒否メッセージを送信するようになりました。Telegram のプロンプトがタイムアウトすると、macOS ではネイティブダイアログでもう一度確認されます（docs/approval-transports.mdを参照）。MCP_WARDEN_APPROVAL_TRANSPORT={telegram|desktop|tui} で実行時に上書きできます。

v0.3.0 の新機能

• preset scaffold — よく使われる API 向けの組み込みテンプレートを 8 種類用意しています（github-read、github-write、notion-read、stripe-read、openai-chat、anthropic-messages、gitea-read、cloudflare-dns）。クックブックからコピー＆ペーストする代わりに、1 つのコマンドで動作するプリセットを生成できます。
• preset from-openapi <url-or-file> — OpenAPI 3.0/3.1 の JSON または YAML 仕様を指定すると、base_url、allowed_paths、allowed_methods、認証方式（Bearer または APIKey-Header）を導出します。HTTP メソッドまたはタグで絞り込めます。
• doctor --deep — 各 HTTP プリセットに対し、安全な読み取り専用のプローブ（ベース URL または最初のリテラルな許可パスへの GET）を実行し、ok / auth_failed / auth_ok_404 / network_error / tls_error / skipped を、経過時間と本文の一部（機密情報は伏せ字）とともに報告します。--include-prompt を指定しない限り、prompt ポリシーのプリセットはスキップします。
• web — TUI を起動せずにプリセットと監査ログを閲覧できる、小規模なローカル専用 Web UI（バインド先はハードコードされた 127.0.0.1）です。このリリースでは読み取り専用です。WebSocket 経由の承認はロードマップに含まれています。
• Telegram 承認トランスポート — 承認プロンプトを Telegram チャットに送信し、インラインの承認／拒否／一定時間承認ボタンを表示する、新しい ApprovalTransport 実装です。Bot トークンは OS のキーチェーンに保存されます。別のチャットからのコールバックは拒否されます。メッセージでは protect_content: true を使用します。[approval.telegram] が設定されている場合に自動的に選択されます。

Web UI の設計に関するメモは docs/web-ui.md をご覧ください。

セキュリティモデル

mcp-warden の脅威モデルとセキュリティ不変条件は docs/threat-model.md に記載されています。概要は次のとおりです。

• シークレットは OS のキーチェーンにのみ保存されます。ディスク上に平文で保存されることも、ログに記録されることもありません。
• proxy_http のレスポンスで上流が認証情報をそのまま返した場合（エコーエンドポイントや、トークンを引用するエラーなど）、エージェントに渡す前に [redacted by mcp-warden] に置き換えます。レスポンスの残りの部分は、信頼されない上流データとしてそのまま渡されます。
• 許可リストの検証は、認証情報を注入する前に実行されます。
• デフォルトの承認ポリシーは prompt です。auto を使用するには、プリセット作成時に --confirm-auto が必要です。
• MCP サーバーは起動時に一度だけ config.toml を読み込んで検証し、その後は再読み込みしません。プリセットを編集した後はサーバーを再起動してください。
• 監査ログは追記専用です。トレイトのインターフェース自体に delete／clear メソッドはありません。
• mcp-warden lock を実行すると、実行中のすべてのサーバーは次の呼び出し時に停止します。ロックを検知したサーバーは再起動するまでロックされたままとなり、unlock には人間による承認が必要です。
• プリセットでは、proxy_http がエージェントに渡す内容に上限を設定し、トリミングできます（max_response_bytes、response_fields）。上流がそのまま返した認証情報は常に除去されます。
• ラップされたサーバー（mcp-warden run）が取得できるのは、そのサーバー用に保存されたキー（server/<name>/<VAR>）のみです。プリセットのシークレットは取得できず、実行するコマンドは設定で固定されています。渡されたキーは、そのキーを受け取るプロセスからは引き続き参照できます。
• 標準出力は MCP プロトコルの通信チャネルです。すべてのログは標準エラー出力に送られます。

リンク

• crates.io：mcp-warden
• MCP Registry 名：mcp-name: io.github.ermoluk/mcp-warden

ライセンス

Apache-2.0 — OSS コアに対する永続的なコミットメントです。LICENSE をご覧ください。

mcp-warden は、これからも永久に完全な機能を無料で利用できます。オープンコアに関するコミットメントをご覧ください。