pytestの失敗をMCPサーバーでClaudeに解析させる — 9原則デバッグの使い方

pytest-mcp-serverは、pytestで失敗したテストを構造化して記録し、決まった9段階のデバッグ原則を1つずつ適用させるための非公式MCPサーバーです。pytest本体やAnthropicが提供するものではなく、個人開発者(GitHubアカウントtosin2013)が公開しているnpmパッケージです。ログをそのまま貼り付けて「原因を教えて」と頼むのとの違いは、失敗の記録とデバッグの進行状況がサーバー側のファイルに残り、セッションをまたいでも「どこまで調べたか」が引き継がれる点にあります。原則をすべて踏むかどうかはClaude次第ですが、少なくとも記録の器としては同じ土台を使い続けられます。

提供される8つのツール

サーバーが公開するツールは、次の8つです。

中心になるのはregister_pytest_failureとdebug_with_principleの組み合わせで、残りのツールは記録の参照・横断分析・動作確認の補助に回ります。

骨格になっている9つのデバッグ原則

debug_with_principleが適用する原則は、ソースコードのDEBUG_PRINCIPLESに固定の9項目として定義されており、npmパッケージ(1.1.6)のREADMEにも一覧があります。

debug_with_principleをprinciple_numberなしで呼び出すと、その失敗のcurrent_debug_step(今どの原則まで進んだか)を自動で参照し、次の原則を適用します。Claudeに「続きから調べて」と頼むだけで、9つの原則を順番に踏む進行管理が成立します。「なぜこの修正に至ったか」という調査過程が、単発の質問応答と違って9ステップの記録としてサーバー側に残る点が、このツールの特徴です。

Claude Codeに接続する

前提はNode.js 18.19.0以上です。npmのenginesは>=18.19.0 <=22.xなので、23系以降のNode.jsでは対象外になります。条件を満たしていれば、npmコマンドでグローバルインストールします。

npm install -g pytest-mcp-server

READMEのセットアップ例はClaude Desktopの設定ファイルに書く形式で示されていますが、Claude Codeではclaude mcp addコマンドで同じ内容を登録します。標準入出力(stdio)モードでサーバーを起動するstartサブコマンドを、そのままClaude Codeに登録します。失敗記録の保存先はDATA_DIR環境変数で指定します(startの--data-dir ./my-dataでも指定できます)。claude mcp addの--scopeは省略するとlocal(そのプロジェクトだけ)です。

claude mcp add --env DATA_DIR=/path/to/pytest-data --transport stdio pytest \
  -- pytest-mcp-server start

登録後は/mcpでConnectedになっているか確認します。DATA_DIRが意図どおりの値になっているかは、pytest-mcp-server check-envで確かめられます。

HTTPサーバーとして起動する選択肢もあり、npm 1.1.6ではpytest-mcp-server start --transport http-streamを使います。MCPの待ち受けは既定ポート3001(MCP_PORT環境変数か--mcp-portで変更)で、URLはhttp://localhost:3001/mcpです。PORT(既定3000)はWeb UI側のポートです。GitHubのmainのREADMEにはstart-httpサブコマンドの記載がありますが、1.1.6のCLIにはありません。この場合はstdio接続とは別に、Claude Code側もHTTPトランスポートで登録し直す必要があります。

いきなりClaude Codeに登録する前に、8つのツールがどう応答するかを確認したいときはMCP Inspectorが使えます。グローバルインストール済みならpytest-mcp-server startをそのままInspectorに渡します。

npx @modelcontextprotocol/inspector pytest-mcp-server start

ブラウザ上でツール一覧を開くと、example_toolという動作確認専用のサンプルツールも並んでいます。これを1回呼んでみて応答が返ってくれば、サーバー自体は正常に起動できているとわかります。8つのツールすべてを個別に叩けるので、実際のテスト失敗を登録する前段階の疎通確認として使えます。

失敗を登録してから原則を進める

典型的な使い方は、失敗したテストの情報をそのまま渡すところから始まります。

test_user_authenticationがAssertionError: Expected status 200, got 401で落ちた。
ファイルはtests/test_auth.pyの45行目。この失敗を登録して

Claudeはregister_pytest_failureに次のような形式で情報を渡し、テスト名・ファイルパス・行番号・エラーメッセージ・トレースバックを記録します。

{
  "name": "register_pytest_failure",
  "arguments": {
    "test_name": "test_user_authentication",
    "file_path": "/tests/test_auth.py",
    "line_number": 45,
    "error_message": "AssertionError: Expected status 200, got 401",
    "traceback": "Full traceback here..."
  }
}

登録時の失敗IDは、登録時刻のミリ秒値(Date.now())の文字列です。以降のツールはこのIDで失敗を指します。

複数の失敗が溜まってきたらanalyze_failuresで横断的に分析します。引数は3つです。group_byはerror_type・file_path・patternから選び、既定はerror_typeです。time_rangeはall・today・week・monthで、既定はallです。include_resolvedの既定はfalseです。同じ原因が別のテストに波及していないかを、エラー種別やファイル単位で確かめられます。

generate_debug_promptは、失敗1件(failure_id)または失敗グループ(group_id)を指定して、detailed・concise・step_by_step・root_causeの4形式でデバッグ用プロンプトを生成するツールです。detailedは根本原因の分析・修正方針・検証手順の3点をまとめて求める形式、conciseは原因と解決策を手短に求める形式、step_by_stepはパターン分析→根本原因の特定→修正案→検証手順の4手順を順に進めるよう指示する形式、root_causeは修正を求めず根本原因の特定だけに絞る形式です。失敗1件を指定した場合はstep_by_stepはdetailedと同じ内容になります。他の担当者への引き継ぎや、別のAIツールに続きを頼むときなど、記録の中身を目的に応じた粒度に整形して取り出す用途に使えます。どの形式が適しているかは渡す相手次第なので、まずはconciseで試して、情報が足りなければdetailedに切り替えるのが手早いやり方です。

登録済みの失敗を一覧・参照する

原則を進める以外にも、記録した失敗を後から見返すためのlist_failuresとget_failure_infoがあります。

今登録されている失敗を全部一覧して

test_user_authenticationの失敗の詳細を教えて

list_failuresは登録済みの全件を返すシンプルなツールで、複数のテストを並行して調べているときに「どれがまだ手を付けていないか」を確認する用途に使えます。get_failure_infoはcurrent_debug_stepを含む詳細情報を返すため、数日空けて作業を再開したときに「前回どこまで進んでいたか」をすぐに思い出す起点になります。テストスイート全体を一度に流して複数の失敗が出た場合でも、1件ずつregister_pytest_failureで登録しておけば、あとからlist_failuresで全体を見渡しながら優先度を付け直せます。pytest自体の使い方に迷ったときのために、pytestのドキュメントガイドを返すpytest_docs_guideというツールも用意されています。

導入前に確認しておきたいこと

npmレジストリでは、pytest-mcp-serverの最新バージョンは1.1.6(2025年5月18日公開)で、初公開は5月15日です。それ以降、更新はありません。README自体は「Production Ready」と明記していますが、パッケージとしての更新はしばらく止まっている状態です。導入前に、自分の使い方が壊れていないかを軽く動作確認しておくと安心です。

もう1つ、READMEに既知の不具合が明記されています。依存しているライブラリmcp-frameworkのバージョン0.2.13に、バリデーションエラーをMCP仕様どおりの"type": "text"ではなく"type": "error"として返してしまう挙動があります。pytest-mcp-server自体のコードではなく、依存先ライブラリの挙動に起因する問題です。これは自動テストフレームワーク(MCP Testing Framework)でサーバーを検証したときにだけ表面化する問題で、README自身も「実際の利用には影響しない」としています。Claude Codeから通常どおり使う分にはこの問題を意識する必要はありませんが、CI等でこのサーバー自体をテストしようとして原因不明のバリデーション失敗に遭遇した場合は、この既知の問題が該当していないか、まず疑ってみるとよいでしょう。

データの保存先はDATA_DIR配下のJSONファイル(failures.jsonとdebug_sessions.json)です。DATA_DIRを指定しなかったときの既定の場所は、npm 1.1.6とGitHubのmainで異なります。

ファイルを直接読み書きする実装で、複数人が同じディレクトリを共有する使い方は想定されていないようです。個人の開発マシンで、いま追っている失敗の進行状況を残す手元ツールと捉えるのが実態に近い理解です。

よくあるつまずき

• DATA_DIRを未設定のまま使う: 起動場所で記録が分散しないよう、登録コマンドのDATA_DIRには絶対パスを指定します。相対パスはサーバーを起動したディレクトリ基準になります
• principle_numberに1〜9の範囲外を渡してエラーになる: ツールは範囲外の値を明示的にエラーとして返します。何も指定しなければ現在のステップから自動で進むので、通常は省略して問題ありません
• 同じ原則をやり直したいのに次に進んでしまう: debug_with_principleは1回の呼び出しごとに次のステップへcurrent_debug_stepを進める設計です。同じ原則を再検討したい場合はprinciple_numberを明示的に指定して呼び出します。原則9に達したあとは、番号を省略して呼んでも9が繰り返されます
• MCP Testing Frameworkでバリデーションエラーが出て動かないと思い込む: mcp-framework 0.2.13起因の問題なので、サーバー側の不具合と決めつけず、先に導入前の節の記載と照らします
• start --transport http-streamで立てたのにstdio接続の設定のまま使おうとする: HTTPで起動した場合は、Claude Code側もHTTPサーバーとして登録し直します

まとめ

1.1.6とGitHubのmainではDATA_DIR未指定時の保存先が違います。入れる版を固定し、DATA_DIRは必ず絶対パスで渡すと、記録は作業ディレクトリに左右されずセッションをまたいで引き継がれます。9原則そのものは地道なデバッグの定石で、価値はそれを記録付きで順に踏ませる点にあります。

Claude CodeでTDDを回す前提の運用はClaude Codeでテスト駆動開発を回す手順、渡す情報の質でデバッグの精度がどう変わるかはClaude Codeデバッグの精度は渡す情報の質で決まるにまとめています。自作・非公式のMCPサーバーの動作を事前に確認する方法はMCP Inspectorの使い方を参照してください。pytestのテストコマンドや命名規則をあらかじめCLAUDE.mdに明文化しておく方法はClaude CodeにpytestのCLAUDE.md規約を教えるにまとめています。