grc-evidence-mcp — ステップバイステップ構築ガイド

Pythonで実際に動作する読み取り専用のGRCエビデンス収集MCPを構築し、Claude Desktopに接続し、自分のGitHubリポジトリに対してテストし、オプションでPlaywrightを使った視覚的エビデンスのキャプチャを追加します。

このガイドは、MCPをこれまでに構築したことがない方でも完了できるように書かれています。Python、ターミナル、API、Claude Codeにすでに慣れている方は、より速く進めることができ、説明は必要なときだけ参照してください。

完成したリポジトリ: [GITHUB REPO LINK]

構築するもの

最終的に、あなたのMCPは次のことができるようになります。

1. 把握しているエビデンスソースを一覧表示する。

2. ブランチ保護とCODEOWNERSに関する実際のGitHubエビデンスを収集する。

3. そのエビデンスをコントロール参照にマッピングする。

4. 完全なエビデンスをローカルのSQLiteに保存し、Claudeには不透明なcollection_idのみを返す。

5. 保存されたエビデンスコレクションをIDで取得する。

6. オプションで、Playwrightで実際のウェブページのスクリーンショットをキャプチャし、視覚的エビデンスとして保存する。

プロジェクト全体の設計ルールはシンプルです。監査対象システムからエビデンスを読み取り、エビデンスを書き込むのはローカルのランディングゾーンのみ。監査対象システムを変更することは決してありません。

ペースを選ぶ

このガイドを上から下まで一度に構築することも、5日間に分けて進めることもできます。

Related MCP server: Change Trace MCP

5日間のパス

1日目 — Claude Codeをセットアップし、基盤を構築する

目標: ローカルエビデンスストレージと1つの可視ツールを備えた、動作するMCPプロジェクトを取得する。

アクション:

• Claude Codeをインストールする。

• 空のプロジェクトフォルダを作成する。

• フォルダ内でClaude Codeを起動する。

• プロンプト1を貼り付ける。

• Claude CodeにPythonプロジェクト、SQLiteバックアップのStateStore、list_evidence_sourcesツールを作成させる。

• プロジェクトをローカルで実行し、先に進む前にインストールエラーを解決する。

完了条件: Claude CodeがMCPを実行でき、list_evidence_sourcesが存在する。

2日目 — MCPをClaude Desktopに接続する

目標: Claude Desktopが構築したMCPを認識できるようにする。

アクション:

• プロンプト2をClaude Codeに貼り付ける。

• Claude Codeに、完全なサーバーパスを使用してClaude DesktopのMCP設定を更新させる。

• Claude Desktopを完全に終了し、再度開く。

• 新しいチャットを開き、ツール/ハンマーアイコンを確認する。

完了条件: list_evidence_sourcesがClaude Desktopのツールとして表示される。

3日目 — 実際のGitHubエビデンスソースを追加する

目標: 「デモのみ」の考え方を、実際の読み取り専用API呼び出しに置き換える。

アクション:

• プロンプト3を貼り付ける。

• この構築に必要な権限のみを持つ、きめ細かいGitHub個人アクセストークンを作成する。

• .env.exampleを.envにコピーし、そこにトークンを追加する。

• トークン自体をClaude DesktopやClaude Codeのチャットに貼り付けることは決してしない。

• 環境/設定の変更後、Claude Desktopを再起動する。

完了条件: MCPに動作するcollect_evidenceツールがあり、トークンがサーバーで利用可能になっている。

4日目 — 実際のエビデンスをテスト、取得、検査する

目標: 実際に管理しているリポジトリに対してMCPが動作することを証明する。

アクション:

• 自分のリポジトリに対してGitHubテストプロンプトを実行する。

• 返されたcollection_idをコピーする。

• Claude Desktopにそのコレクションを取得するよう依頼する。

• ブランチ保護とCODEOWNERSの結果を確認する。

• 「存在しない」結果をコントロールギャップとして扱う前に、404の制限に関するセクションを読む。

完了条件: ライブのGitHub API呼び出しによって生成された保存レコードを取得した。

5日目 — 視覚的エビデンスを追加し、クリーンアップして公開する

目標: プロジェクトをポートフォリオにできる状態にする。

アクション:

• オプションのPlaywrightエクストラとChromiumをインストールする。

• collect_visual_evidenceを追加または確認する。

• アクセスを許可されている実際のページのスクリーンショットをキャプチャする。

• スクリーンショットのエビデンスコレクションを取得し、そのメタデータを検査する。

• READMEをクリーンアップし、.envが無視されることを確認し、プロジェクトをGitHubにプッシュする。

• チャレンジに参加する場合は、チャレンジの指示に従ってリポジトリを提出する。

完了条件: リポジトリが、MCPが何をするか、実行方法、制限事項を説明し、シークレットを含まない。

始める前に

必要なもの:

• ターミナルを備えたコンピュータ。

• Claude Codeを使用できるClaudeアカウント。

• デスクトップツール部分のウォークスルー用のClaude Desktop。

• GitHubアカウントへのアクセスと、テストを許可されている少なくとも1つのリポジトリ。

• Python 3.10以降。

• マシンにまだない場合はNode.js。

完全に初心者の場合

始める前にPythonのすべての行を理解する必要はありません。この構築中のあなたの仕事は、各コンポーネントが何を担当し、どのようなデータが入り、何が返され、セキュリティ境界がどこにあるかを理解することです。Claude Codeがファイルを作成または変更するとき、不明な点があれば、先に進む前にそのファイルを平易な英語で説明するよう依頼してください。

より技術的な場合

生成されたファイルを検査し、各プロンプトの間でテストを実行し、実装の選択についてClaude Codeに異議を唱えることができます。完成したリポジトリは参考実装であり、すべてのファイルが同一である必要はありません。

ステップ1 — Claude Codeをインストールする

実行:

npm install -g @anthropic-ai/claude-code

Node.jsがないためにエラーが発生した場合は、Node.jsをインストールしてから、コマンドを再度実行してください。

Claude Codeを起動:

claude

初回実行時にサインインが求められます。

この構築は意図的にターミナルファーストです。完了するために別のエディタは必要ありません。

ステップ2 — プロジェクトフォルダを作成する

mkdir my-evidence-mcp
cd my-evidence-mcp
claude

この時点から、ビルドプロンプトを順番にClaude Codeに貼り付けます。

プロンプト1 — 基盤を構築する

Help me build a small MCP server in Python called grc-evidence-mcp, using
FastMCP over stdio, that I'll connect to Claude Desktop.

Purpose: read-only compliance evidence collection. It reads evidence FROM
systems and writes evidence TO a local landing zone — it must never modify
the audited system itself.

Build the foundation first, not real sources yet:

1. A StateStore class backed by SQLite — save(record) returns an opaque id,
   get(id) returns the record back. That id is the only handle anything
   else gets to a stored record.
2. One tool: list_evidence_sources — returns available sources and flags
   which ones are just stubs for now. Register one stub source so the
   list isn't empty.

Get this running and visible as a tool in Claude Code before we add
anything real.

このステップで学べること

StateStoreは、会話と完全なエビデンスレコードを分離します。収集したすべてのエビデンスを直接モデルに渡す代わりに、サーバーはそれをローカルに保存し、ClaudeにIDを渡します。Claudeは後でそのIDを渡すことができ、エビデンス自体を再現する必要はありません。

チェックポイント

先に進む前に、Claude Codeに以下を表示するよう依頼してください:

• MCPサーバーがどこで起動するか、

• StateStoreがどこにデータを書き込むか、

• list_evidence_sourcesがどこに登録されているか、

• サーバーが正常に起動することを確認するために使用したコマンド。

プロンプト2 — Claude Desktopに接続する

Add this server to my Claude Desktop config at ~/Library/Application
Support/Claude/claude_desktop_config.json. Use the full path to the
server, not just the command name, so it doesn't rely on my terminal's
PATH.

このパスは、ウォークスルーで使用されるmacOSパスです。別のオペレーティングシステムを使用している場合は、何かを編集する前に、Claude CodeにそのオペレーティングシステムのClaude Desktop MCP設定ファイルを特定するよう依頼してください。

サーバーコマンドには完全なパスを使用してください。Claude Desktopは、ターミナルと同じPATHを継承するとは限りません。

次に、Claude Desktopを完全に終了して再度開きます。通常のウィンドウを閉じるかリロードしても、MCP設定が再読み込みされない場合があります。

新しいチャットを開き、ツール/ハンマーアイコンを確認します。list_evidence_sourcesが表示されるはずです。

ツールが表示されない場合

次の順序で確認してください:

1. Claude Codeは設定を正しいClaude Desktop設定ファイルに保存しましたか?

2. 設定は完全な実行可能ファイル/サーバーパスを使用していますか?

3. MCPはターミナルから正常に起動しますか?

4. Claude Desktopを完全に終了して再度開きましたか?

5. 再起動後に新しいチャットを開きましたか?

基盤ツールが表示されるまで、GitHubのステップに進まないでください。

プロンプト3 — 実際のGitHubソースを追加する

Now build the first real source: GitHub.

Add a collect_evidence(source_name, params) tool that, for source_name=
"github", checks branch protection status and CODEOWNERS presence on a
repo I specify (owner/repo/branch), using my own GitHub token
(read-only — Administration:read and Contents:read, nothing else).

Map each result to a control reference:
- branch protection present → SOC2-CC8.1, ISO27001-A.8.32
- CODEOWNERS present → SOC2-CC8.1, ISO27001-A.5.3

Return a collection_id from StateStore, not the raw evidence directly.
I want to run this against a real repo of mine and see actual results,
not sample data.

GitHubトークンを作成する

テストする予定のリポジトリ用にきめ細かい個人アクセストークンを作成します。次の権限のみを付与します:

• Administration: read

• Contents: read

すでに持っているからといって、より広範なトークンを再利用しないでください。

トークンを.envに配置する

完成したリポジトリには.env.exampleが含まれています。それをコピーします:

cp .env.example .env

次に設定します:

GITHUB_TOKEN=your_token_value_here

完成したリポジトリは、GitHubコレクターが起動するときにこの.envファイルを読み込みます。

実際のトークンをClaude DesktopやClaude Codeのメッセージに貼り付けることは決してしないでください。 トークンは会話ではなく環境に属します。また、.envがコミットされないように.gitignoreに含めてください。

トークン/環境を変更した後、Claude Desktopを完全に再起動します。

ステップ4 — 自分のリポジトリに対してテストする

Claude Desktopで、次のように尋ねます:

Check branch protection and CODEOWNERS on [your-username]/[your-repo],
branch main.

これにより、指定したリポジトリに対して実際のGitHub API呼び出しが行われるはずです。

ツールはcollection_idを返すはずであり、完全な生レコードではありません。

次に、次のように尋ねます:

Get the evidence collection with id [collection_id].

保存されたエビデンスレコードが表示されるはずです。

検査する項目

次のものを探してください:

• リポジトリとブランチ名、

• ブランチ保護の結果、

• CODEOWNERSの結果、

• マッピングされたコントロール参照、

• 基礎となるエビデンス/ステータスの詳細、

• コレクションのタイムスタンプ。

これが、プロジェクトが単なるデモを超えるポイントです。管理している実際のシステムからエビデンスを収集し、取得しました。

重要な制限 — GitHubの404は曖昧です

GitHubは、ブランチ保護が設定されていない場合に404を返すことがありますが、404はリポジトリ/ブランチが見つからないか、呼び出し元が設定を確認するための十分なアクセス権を持っていない場合にも発生する可能性があります。

現在のGitHubコレクターは応答の詳細を保持しますが、404の結果をpresent: falseとして記録します。それを確認されたコントロールギャップとして自動的に扱わないでください。 人間のレビュー担当者が、結果が「未設定」を意味するのか「確認できなかった」を意味するのかを検証する必要があります。

その区別は優れたGRCエンジニアリングの一部です。「いいえ」と「わかりません」は同じ調査結果ではありません。

ボーナス — Playwrightで視覚的エビデンスを追加する

これはオプションです。コアMCPはこれなしで動作します。

完成したリポジトリはヘッドレスChromiumを備えたPlaywrightを使用します。Claude for Chrome拡張機能には依存しません。

オプションパッケージとブラウザをインストールします:

pip install -e ".[screenshot]"
playwright install chromium

プロンプトから構築する場合は、次を使用します:

Add a tool collect_visual_evidence(url, subject) that opens the given URL
in headless Chromium via Playwright, captures a full-page screenshot, and
stores it the same way collect_evidence does — save the result to
StateStore, return only a collection_id, never the raw image bytes.

Classify the result conservatively: a successful page load can be stored
as present; a 401/403 authentication wall, a 404, or a navigation failure
must not be treated as proof that a control is missing. Record those as
indeterminate or error as appropriate. Burn a timestamp using the local
machine timezone into the screenshot metadata so a reviewer knows when
it was captured.

次に試します:

Capture visual evidence of https://github.com/[your-username]/[your-repo]/settings/branches.

スクリーンショットツールは、PNGをMCPのローカルスクリーンショットディレクトリに保存し、そのメタデータをStateStoreに保存します。そのスクリーンショットエビデンスレコードの新しいcollection_idを返します。

スクリーンショットは、キャプチャ時点のページの外観を示します。それ自体がコントロールが有効であることの証明ではありません。実装は、認証壁と404をコントロールの失敗ではなく不確定として意図的に扱います。視覚的キャプチャはページ固有であり、ローカルデスクトップのスクリーンショットは撮影しません。

完成したリポジトリの内容

• grc_evidence_mcp/store.py — 不透明なIDを持つSQLiteバックアップのStateStore。

• grc_evidence_mcp/server.py — MCPツール登録とエビデンス保存ワークフロー。

• grc_evidence_mcp/github.py — 読み取り専用のGitHub APIエビデンスコレクター。

• grc_evidence_mcp/screenshot.py — オプションのPlaywrightスクリーンショットコレクター。

• .env.example — GitHubトークン変数の安全なテンプレート。

• .gitignore — .envなどのローカルシークレットがコミットされないようにします。

• pyproject.toml — Python依存関係とオプションのスクリーンショットエクストラ。

コアツール:

• list_evidence_sources

• collect_evidence

• get_evidence_collection

オプションのボーナスツール:

• collect_visual_evidence

症状別トラブルシューティング

claudeコマンドが見つからない

必要に応じてNode.jsをインストールし、Claude Codeのnpmインストールを再実行します。

MCPツールがClaude Desktopに表示されない

設定の場所と完全なサーバーパスを確認し、サーバーがターミナルで起動することを確認し、Claude Desktopを完全に再起動してから、新しいチャットを開きます。

GITHUB_TOKEN is not set

.envがプロジェクトルートに存在し、GITHUB_TOKEN=...を含み、.envを読み込む更新されたプロジェクトを実行していることを確認します。環境/設定を変更した後、Claude Desktopを再起動します。

GitHubが401を返す

トークンが無効、期限切れ、または正しく読み取られていません。

GitHubが403を返す

トークン/アカウントが、リポジトリまたは設定への必要な読み取りアクセス権を持っていない可能性があります。

GitHubが404を返す

すぐにコントロールの失敗と呼んではいけません。リポジトリ、ブランチ、トークンアクセス、および基になるGitHub応答を確認してください。

Playwrightがインストールされていない

実行:

pip install -e ".[screenshot]"
playwright install chromium

スクリーンショットにログインページが表示される

それでも実際のスクリーンショットですが、コントロールの状態を証明するものではありません。不確定として扱い、アクセスが許可されている場合は、再試行する前に適切に認証してください。

リポジトリを公開する前に

• .env がコミットされないようにしてください。

• リポジトリ内にトークンやその他のシークレットがないか検索してください。

• README の制限事項セクションを維持してください。

• GitHub の呼び出しが読み取り専用であることを説明してください。

• スクリーンショットはキャプチャ時点のページ状態を示すものであり、コントロールの有効性を示すものではないことを説明してください。

• 他の人がビルドを再現できるように、十分なセットアップ手順を含めてください。

• スクリーンショットや例では自分のリポジトリを使用するか、公開すべきでないものはすべて伏せてください。

チャレンジについて

登録者100人達成を記念して、$306 のプレゼント — Claude Pro 1年分と GRC Engineering Club メンバーシップ1年分を提供します。

参加方法：

1. 登録していること。

2. MCP を構築すること。

3. 構築したものの GitHub リポジトリを提出すること。

資格のある応募の中から抽選で1名の当選者を選出します。プロジェクトに Built with BuildinginGRC のタグを付けてください。

最終学習チェック

プロジェクトを完了と呼ぶ前に、以下の5つの点を自分の言葉で説明できる必要があります。

1. 監査対象システムに対して MCP が読み取り専用である理由。

2. サーバーが証跡を保存し、すべてを直接返すのではなく collection_id を返す理由。

3. GitHub トークンがコレクターが必要とする権限のみを持つべき理由。

4. 404 やログイン画面が、コントロールが存在しないことの自動的な証明にならない理由。

5. API の結果が証明することと、スクリーンショットが証明することの違い。

それらを説明できれば、あなたはプロジェクトをコピーしただけではありません — その背後にある GRC エンジニアリングの意思決定を理解しているのです。