MCP Inspector

MCP Inspector

Model Context Protocol（MCP）サーバーを検査するための開発者ツールです。単一のパッケージ @modelcontextprotocol/inspector として提供され、サーバーを検査する4つの方法を備えています。

• Web — Vite + React + Mantine を使用した、Node バックエンド付きのシングルページアプリです。
• CLI — 自動化、CI、高速なエージェントのフィードバックループに使える、スクリプト実行可能なコマンドラインクライアントです。
• TUI — Ink で構築された、対話型のターミナル UI です。
• mcpdo (experimental) — 接続用 CLI です。一度接続すれば、暗黙的なローカルデーモンを通じて、名前付き接続に対する多数のコマンドを実行できます。clients/mcpdo を参照してください。

最初の3つは、1つのグローバルな mcp-inspector バイナリを通じて実行されます。mcpdo は同じパッケージに含まれる2つ目のバイナリです。

npx @modelcontextprotocol/inspector                   # web UI (default)
npx @modelcontextprotocol/inspector --cli             # CLI
npx @modelcontextprotocol/inspector --tui             # TUI
npx -p @modelcontextprotocol/inspector mcpdo --help   # mcpdo

警告

Inspector は OAuth トークン、OAuth クライアントシークレット、stdio の env: 値などのシークレットを管理し、利用可能な場合はデフォルトで OS のキーチェーンに保存します。 キーチェーンのないマシン（libsecret または Secret Service がない Linux、ヘッドレスセッションや SSH セッション、Termux、ボリュームをマウントしたコンテナーなど）では、代わりに ~/.mcp-inspector/secrets.json に保存されます。キーを指定しない限り、暗号化されません。キーチェーンを復元する方法、ファイルを暗号化する方法、またはシークレットをメモリー内のみに保持する方法については、シークレットの保存場所を参照してください。

v1 からアップグレードしますか？ v1 → v2 移行ガイドをお読みください。CLI フラグ、新しい --config と --catalog の使い分け、Node の必要バージョンの引き上げ、および提供されなくなったものについて説明しています。

リポジトリの状況。 この Inspector は v2 系統です。開発は v2/main（開発ブランチ。v2 のすべての PR はこのブランチを対象とします）で進行中で、マイルストーンリリース時に main にマージされます。main はデフォルトブランチで、npm の latest タグで公開された最新の v2 リリースを保持します。旧 v1 系統は v1/main にあり、セキュリティ修正のみが行われます。このブランチから npm の v1-latest タグへ直接公開されます（npx @modelcontextprotocol/inspector@v1-latest）。ブランチとボードの規約については、AGENTS.md を参照してください。

クイックスタート（開発）

Node >=22.19.0 が必要です。

npm install          # at the repo root; postinstall cascades into every client
npm run build        # web → cli → tui → launcher

日々の Web 開発では、Vite を直接実行してください。HMR が高速で、ランチャーのビルドも不要です。

cd clients/web && npm run dev

ランチャーを使用するスクリプトはビルド済みのランチャーを実行するため、先にビルドしてください。

npm run web        # prod web launcher against clients/web/dist
npm run web:dev    # web launcher in --dev mode (Vite)

v2 は npm ワークスペースではありません。clients/* 以下の各クライアントはそれぞれ独自の package.json と node_modules を保持し、共有コードは core/ に置かれ、ビルド時の @inspector/core エイリアス経由で利用されます。core/ がインポートするすべてのランタイム依存関係は、リポジトリルートの package.json に一度だけ宣言します。各クライアントでは、そのクライアントだけが使用するもの（UI スタック、バンドラーにインライン化するパッケージ、開発ツール）のみを宣言するため、clients/cli と clients/launcher には独自のランタイム依存関係がありません。依存関係の追加方法（ルートかクライアントか、dependencies か devDependencies か、バンドラーの external リストなど）については、local-dev スキルを参照してください。

プロジェクト構成

inspector/
├── clients/
│   ├── web/          Web client (Vite + React + Mantine). src/ = browser app; server/ = Node backend
│   ├── cli/          CLI client (tsup bundle, @inspector/core alias)
│   ├── mcpdo/   Experimental connection CLI (`mcpdo` bin) — bundled into the
│   │                 published package; see clients/mcpdo/README.md
│   ├── tui/          TUI client (Ink + React, tsup bundle)
│   └── launcher/     Shared launcher — provides the `mcp-inspector` bin, dispatches to web/cli/tui
├── core/             Shared code consumed via the `@inspector/core` alias (no package.json)
├── test-servers/     Composable MCP test servers + fixtures used by integration and smoke tests
├── scripts/          Root build/verify tooling (install cascade, smokes, the verify:* guards),
│                     repo automation run from CI (the dependency, Dependabot-alert and SDK sweeps),
│                     maintainer-workflow helpers (the pr:*, board:*, advisory:*,
│                     release:notes, release:tag and action:resolve-pin aliases)
│                     and the Docker image's HEALTHCHECK probe
├── docs/             Task-oriented guides — see below
├── specification/    Design/build specifications
├── skills/           End-user agent skills (e.g. skills/mcpdo teaches an agent to
│                     drive the `mcpdo` CLI) — distinct from .claude/skills/,
│                     which holds this repo's own procedures
├── .claude/skills/   Agent skills: the repo's procedures, invokable by name
├── AGENTS.md         Contribution rules for agents AND humans
└── README.md         You are here

各クライアントの README には、そのクライアント固有の詳細が記載されています。 web · cli · mcpdo · tui · launcher。

ドキュメント

ガイド	内容
アーキテクチャ	@inspector/core の共有パッケージと、Web クライアントの「ダムコンポーネント」＋ Storybook のアプローチ
テストと品質ゲート	各 validate／coverage／smoke／verify:* スクリプトの対象、GitHub CI とローカルゲートの分担、サポート対象ブラウザー
スキルの作成	実際に動作するスキルの説明と、それを測定する評価ケースの書き方 — 有効なケースの形式と調整の反復プロセス
テストサーバー	コンポーザブルなテストサーバーと各機能のショーケース設定 — 実行するもの、クリックするもの、壊れたビルドで起きたこと
公開	tarball に含まれるもの、パッケージングの不変条件、pack:verify
HTTPS 経由での Web UI の提供	INSPECTOR_TLS_KEY_PATH／INSPECTOR_TLS_CERT_PATH、信頼できるローカル mkcert の設定、カスタムホスト名と ALLOWED_ORIGINS、およびプライベート CA サーバーへのアウトバウンド接続用の NODE_EXTRA_CA_CERTS
Docker	コンテナーイメージの実行 — ポート、ボリューム、コンテナー内でシークレットを永続化する方法
シークレットの保存場所	各ランタイムでシークレットストアがどのように選ばれるか — OS のキーチェーン、secrets.json、またはメモリ — およびファイル暗号化、ロック、キーチェーンへの復帰
v1 から v2 への移行	CLI フラグの対応、--config と --catalog の違い、Node エンジンのバージョン引き上げ、環境変数名の変更
環境変数	ランタイムの動作を変えるすべての変数 — 認証、ポート、ストレージ、シークレットストア、ロギング、プロキシ — および自己署名サーバー用の Node TLS 変数
MCP サーバーの設定	Inspector が接続するサーバーと設定ファイルの形式
MCP App のレビュー	自動化された App ツールレビューのための、CLI 優先からワンショット Web への手順
MCP サーバーのスモークテスト	シェルまたは CI ジョブ向けの、接続 → 一覧表示 → 呼び出し → アサーションのワークフロー：--format json と jq、終了コードの対応表、OAuth を非対話型に保つ方法
遡及的な DCO 承認	DCO チェックが実行されていない間に Signed-off-by: なしでマージされた 10 件のコミットと、それぞれについて作成者が署名した承認
ランチャーと設定の統合	ランチャーがクライアントを起動するのではなく、プロセス内で実行する理由
ロードマップ、2026 年 8 月 → 2027 年 2 月	6 か月の計画：公開された MCP ロードマップに沿った仕様準拠の取り組み、公式拡張機能のサポート、選択した体験向上の取り組み
MCP Inspector：私たちの AI ソフトウェアファクトリー	v2.0.0 以降の実際の貢献の進め方 — Issue 主導のエンドツーエンドの作業、ルールとスキルの分担、Dependabot に代わる一括更新、品質ゲート、今後の展望

テストと品質ゲート

各クライアントはそれぞれのフォルダーで自己検証し、ルートのスクリプトがそれらを連結します。ルートには集約 test スクリプトはありません。

npm run validate     # fast inner loop: format:check + lint + typecheck + build + unit tests
npm run coverage     # the per-file ≥90% gate (lines/statements/functions/branches)
npm run local:gate   # MANDATORY before pushing — every GitHub CI check, plus one local-only one

npm run local:gate は、以下のすべてのチェックに加えて、スモークテストと Storybook のテストを連結して実行します。テストと品質ゲート では、ステージの一覧と各ステージの対象範囲、およびローカル専用のステージがある理由を説明しています。テストのルール自体は AGENTS.md に記載されています。

貢献 — AGENTS.md、CLAUDE.md、スキル

AGENTS.md は、このコードベースを変更する際の規約であり、人間と AI エージェントの双方に適用されます。 エージェント専用の定型文書ではなく、バージョンやラベルの規約、TypeScript と Mantine／React の標準、テストとカバレッジの要件、必須のプッシュ前チェックなど、プロジェクトの実際の ルール が記載されています。変更を始める前に読み、構成、ツール、ルールを変更したときは最新の状態に保ってください。

リポジトリの 手順 — コマンドや実際の ID を含む複数ステップのレシピ — は、代わりに .claude/skills/ に、手順ごとにディレクトリを分けて保存されています。これにより、タスクで必要になったときだけ読み込まれます。通常のコミット済み Markdown なので、スキルを理解しないエージェントでも読むことができ、AGENTS.md には手順の一覧が記載されています。Claude Code のユーザーは名前で呼び出します（/release、/issue-triage、…）。

CLAUDE.md は Claude Code が自動的に読み込むエントリーポイントで、AGENTS.md を含んでいるため、エージェントと人間は同じ信頼できる情報源に基づいて作業できます。AGENTS.md を読む別のエージェントを使う場合も、同じルールが適用されます。

ここで明記しておきたい重要なルールがあります。すべての作業は Issue に基づいて進めます。 作業を始める前に、v2 プロジェクトボードで追跡用 Issue を見つけるか作成してください。PR は v2/main に対して作成し、Closes #<issue> を記載してください。外部からの貢献は プルリクエストではなく Issue として受け付けます。詳しくは CONTRIBUTING.md を参照してください。

ライセンス

LICENSE を参照してください。MCP プロジェクトは MIT License から Apache-2.0 への移行中です。新たなコードの貢献は Apache-2.0、仕様を除くドキュメントは CC-BY-4.0 のライセンスが適用されます。また、作成者が当初 MIT のライセンスを適用し、再ライセンスへの同意を与えていない貢献は、引き続き MIT の下で提供されます。このファイルには Apache-2.0 と MIT の全文が記載され、CC-BY-4.0 の法的条文へのリンクも掲載されています。