Semgrep MCPの使い方 — Claude Codeの生成コードを自動スキャン
Semgrep MCPの使い方は、Claude Codeでプラグインを1行入れてSemgrepにログインするだけです。Guardianへの統合後の導入手順、ローカル版との違い、つまずきを解説します。
Semgrep MCPは、静的解析ツールSemgrepをMCP経由でClaude Codeから呼び出す公式サーバーです。10,000超のルールで脆弱性を検知するSemgrep本体の機能を、コード片を渡すだけのツール呼び出しとして使えます。Claude Code向けの現行の入り口は単体のMCPサーバーではなく、MCPサーバー・Hooks・SkillsをまとめたSemgrep Guardianという統合パッケージです。
Semgrep MCPの使い方 — 最短の3手順
Claude CodeでSemgrepを使うには、次の3手順で足ります。
- ターミナルで
claude plugin install semgrep@claude-plugins-officialを実行する claudeを起動し、ブラウザーでSemgrepにログインする- 以後、Claude Codeがファイルを書くたびに自動でスキャンされる
Semgrepアカウントは必要ですが、Semgrep CLIのインストールは要りません。ローカル版やclaude mcp addによる登録は、後の節で扱います。
Semgrep MCPとは — Guardianへの統合の経緯
もともとSemgrep MCPはsemgrep/mcpという独立リポジトリでベータ公開されていました。2025年10月にこのリポジトリはアーカイブされ、機能はSemgrep本体のリポジトリ(semgrep/semgrep)内に移管されています。以後のMCPサーバーはsemgrepバイナリのmcpサブコマンドとして配布され、単体パッケージのインストールは不要になりました。
Semgrep公式のMCPサーバーは、コミュニティ製のmcp-server-semgrepを着想源にしたと、READMEに記されています。非公式の実験から公式ツールへ、そして単体サーバーからGuardianという統合パッケージへと、比較的短期間で立場が変わってきた領域です。動いているアプリを攻撃側の視点で調べるDASTを足すなら、NightVisionプラグインの導入手順があります。
この移管に合わせて、導線は「Semgrep Guardian」という名称に再編されました。対象はClaude CodeとCursorです。GuardianはMCPサーバー単体ではなく、MCPサーバー・Hooks・Skillsを1回の導入にまとめたものです。エージェントが生成したファイルをSemgrep Code(SAST)・Supply Chain(SCA)・Secretsの3種で調べます。
スキャンはCIではなく、コードを書いた直後に開発者のマシン上で走ります。
Guardianが1回のスキャンで行うこと
- 1
エージェントがファイルを書く
Claude Codeが新規作成または編集します。
- 2
スキャンが起動する
フック(統合によってはMCPツール呼び出し)が、いま生成された内容をSemgrepに渡します。
- 3
検出結果が返る
指摘があれば、エージェントが受け取り、コードを再生成するよう促されます。
- 4
エージェントが再生成を決める
再生成した場合は、新しいコードがもう一度スキャンされます。
コミット前に走るので、CIやプラットフォームのスキャンを置き換えるものではなく、補う位置にあります。
Claude Codeに導入する — 推奨はプラグイン経由
公式ドキュメントはClaude Codeを「推奨セットアップ」と位置付けており、リモートのホスト型サーバーを使うプラグイン導入がもっとも手数が少ない方法です。
claude plugin install semgrep@claude-plugins-officialインストール後、ターミナルでclaudeを起動するとブラウザーでのSemgrepログインを求められます。OAuthによる1回限りのログインで、アクセストークンはSemgrep側が自動更新します。この経路ではSemgrepのホスト型リモートサーバーを使うため、ローカルへのSemgrep CLIインストールは不要です。
プラグインはPostToolUse系のフックを登録し、Claude Codeが書いたファイルを都度スキャンします。前提はSemgrepアカウントとclaudeコマンドです。Windows環境ではWSL(Windows Subsystem for Linux)が必須で、ネイティブWindowsは非対応です。
認証情報は~/.semgrep/guardian.ymlに保存されます。ローカルCLI経由(semgrep login)では~/.semgrep/settings.ymlです。guardian.ymlにOAuth認証情報があると、settings.ymlのAPIトークンより優先されます。想定と違うアカウントでスキャンが走るときは、この優先順位を疑います。
CLIの認証情報を消すにはsemgrep logoutを使います。Claude Codeで従来のAPIトークン方式に戻したいときは、Guardian MCPに従来の方法でSemgrepにログインするよう頼みます。
ローカルCLI経由で使う場合
組織のポリシーに沿ったルールセットで走らせたい、あるいはローカル実行に寄せたい場合は、Semgrep CLIを先に導入したうえでプラグインをローカル版に切り替えます。
# インストール方法はいずれか1つ(pipx/uvが推奨、Homebrewはベストエフォート)
pipx install semgrep
uv tool install semgrep
semgrep login && semgrep install-semgrep-proSemgrep CLIはインストール方法に関わらず、実行時にPython 3.10以上を必要とします。既存のPython環境が古い場合は、CLI導入前にバージョンを確認しておくとつまずきません。
CLI導入後は、Claude Code内で/pluginからDiscoverタブを開いてSemgrepを検索してインストールし、/reload-pluginsで読み込みます。このローカル版はsemgrep/guardian-localリポジトリで配布されています。Semgrep本体のREADMEは、Claude Codeの手順に/setup-semgrep-plugin(Semgrep CLIのインストールも行う)も載せています。
guardian-localのREADMEには別経路もあります。まず/plugin marketplace add semgrep/guardian-localを実行します。続けて/plugin install semgrep@semgrep-marketplace、最後に/reload-pluginsです。Guardian公式マーケット経由が既定で、こちらはうまくいかないときの予備とされています。
MCPサーバー単体として素のツール群だけを使いたい場合は、claude mcp addでも登録できます。semgrep mcpはPro Engineが前提なので、前のコマンドのsemgrep install-semgrep-proまで済ませてから実行します。
claude mcp add semgrep -- semgrep mcpリモートとローカルでルールセットが違う
Guardianはリモートかローカルかで、適用されるルールセットが変わります。公式はこの違いを2経路でもっとも影響が大きい点としています。
どのルールで走るか
リモートプラグイン(既定)
guardian-defaultという固定のルールセットで走り、組織のPoliciesは反映されません。Policiesを調整済みでも、CIやプラットフォームのスキャンが報告する指摘をGuardianが拾わないことがあります。
ローカルプラグイン・他IDE統合
Semgrepの組織アカウントでPoliciesに有効化したルールで走ります。Claude Code以外の統合ではsemgrep_scanツールがMCPサーバー経由で呼ばれます。
guardian-defaultはp/defaultをもとにしたルールセットで、エージェントが修正やサニタイザーを適用できるルールだけを含みます。確実な修正方法を持たないルールは、エージェントがコードを誤って書き換える原因になるため外されています。カスタムルールが必要な場合は、SemgrepのSlackコミュニティの#mcpチャンネルで相談するよう案内されています。
MCPツールの構成
Semgrep本体のリポジトリに統合されて以降、公開されるツールは実行環境によって出し入れされます。常に両方が同時に使えるわけではありません。
| 分類 | ツール | 役割 |
|---|---|---|
| スキャン(ローカルのみ) | ツールsemgrep_scan | 役割ワークスペース内のファイルパスを渡してスキャン |
| スキャン(リモートのみ) | ツールsemgrep_scan_remote | 役割コード内容を直接渡すホスト型スキャン |
| スキャン | ツールsemgrep_scan_with_custom_rule | 役割自作のSemgrepルールでスキャン |
| スキャン(ローカルのみ) | ツールsemgrep_scan_supply_chain | 役割依存関係の変更・追加・lockfile更新時に第三者ライブラリの脆弱性を調べる |
| 解析 | ツールget_abstract_syntax_tree | 役割コードの抽象構文木(AST)を出力 |
| クラウド連携 | ツールsemgrep_findings | 役割Semgrep AppSec Platformの検出結果を取得(要トークン) |
| クラウド連携 | ツールsemgrep_whoami | 役割現在ログイン中のユーザー情報を返す(stdio接続では無効) |
| メタ | ツールget_supported_languages | 役割対応言語一覧を返す |
| メタ | ツールsemgrep_rule_schema | 役割ルールのJSON Schemaを取得 |
semgrep_scanはcode_filesに絶対パスの一覧を受け取ります。semgrep_scan_with_custom_ruleはcode_filesに加えてrule(YAMLのルール文字列)を受け取ります。これに加えてwrite_custom_semgrep_ruleというプロンプトが用意されており、Claude自身に新しいSemgrepルールの書き方を案内させることもできます。
ツールは環境変数で個別に無効化できます。値をtrueにすると無効になる変数は次の8つです。
SEMGREP_SCAN_DISABLEDSEMGREP_SCAN_REMOTE_DISABLEDSEMGREP_SCAN_WITH_CUSTOM_RULE_DISABLEDSEMGREP_SCAN_SUPPLY_CHAIN_DISABLEDSEMGREP_FINDINGS_DISABLEDGET_ABSTRACT_SYNTAX_TREE_DISABLEDGET_SUPPORTED_LANGUAGES_DISABLEDSEMGREP_RULE_SCHEMA_DISABLED
SEMGREP_IS_HOSTED=trueにすると、semgrep_scanの代わりにsemgrep_scan_remoteが出ます。
検出結果を1件ずつ確認するフロー
スキャン結果の確認は、findings elicitationというフローで行えます。既定では無効で、環境変数SEMGREP_FINDINGS_ELICITATION_ENABLEDをtrueにすると有効になります。有効な場合、検出された1件ごとに深刻度・ルールID・ファイル位置を提示し、真陽性(true positive)・誤検知(false positive)・スキップのいずれかを選ばせます。
選んだ内容はSemgrep側の計測に記録されるだけで、返される検出結果そのものは変わりません。この確認を呼ぶのは、ローカルのsemgrep_scanとsemgrep_scan_with_custom_ruleです。semgrep_scan_supply_chainとリモートのsemgrep_scan_remoteは呼びません。
セットアップ自体をプロンプトに任せる
素のMCPサーバーとして接続した場合、ログインとルール追記を手作業でやる代わりにsetup_semgrep_mcpというMCPプロンプトを呼ぶ方法もあります。Claude Codeに対しては、次の2つを自動でやらせるプロンプト定義です。1つ目はログイン(semgrep login --force)とSemgrep Proのインストール(semgrep install-semgrep-pro)です。2つ目は~/.claude/CLAUDE.mdへの次のルールの追記です。
# Security
- Always look first to any semgrep mcp servers for code security needs
- Whenever you generate code or commands, you MUST first ensure safety
by scanning the content with the semgrep_scan toolこのルールがCLAUDE.mdに入ると、以後のセッションで、コード生成時にsemgrep_scanを呼ぶようClaudeに指示する形になります。Guardianのプラグイン導入がフックによる自動スキャンを仕組み化するのに対し、こちらはCLAUDE.mdの指示文でエージェントの振る舞いとして促す方式です。
Claude Code純正のsecurity-guidanceとの違い
Claude Codeには公式プラグインのsecurity-guidanceがあります。変更したコードをその場でレビューする仕組みです。両者は検知の性格が異なります。
| 観点 | Semgrep MCP / Guardian | security-guidance |
|---|---|---|
| 検知方式 | Semgrep MCP / Guardian10,000超のルールによる決定論的な静的解析 | security-guidance編集ごとのパターン照合・ターン終了時の差分レビュー・commit時のレビューの3層 |
| 対応言語・ルール数 | Semgrep MCP / Guardian多言語・レジストリ経由で継続的に追加。リモート経路のguardian-defaultは修正可能なルールのみ | security-guidance例示パターン+モデルレビュー(追加ルール可) |
| 提供元 | Semgrep MCP / GuardianSemgrep社 | security-guidanceAnthropic公式 |
| 追加設定 | Semgrep MCP / GuardianSemgrepアカウントが必要 | security-guidanceSemgrepアカウントは不要。Pythonとgitリポジトリが前提 |
追加のアカウントを増やしたくない場合は、security-guidanceだけで様子を見る選択肢もあります。
get_abstract_syntax_treeは脆弱性スキャンとは別系統のツールで、渡したコードの抽象構文木をそのまま返します。ルールを書くときに、コードの構造をパーサーがどう見ているかを確かめたい場面で使えます。対応言語の一覧は固定値ではなく、get_supported_languagesツールがSemgrep本体から動的に取得して返します。
Semgrep AppSec Platformとの連携
semgrep_findingsツールでクラウド側の検出結果を取得するには、APIトークンを使う場合の手順です。
- semgrep.dev/loginでSemgrepアカウントにログイン(未登録ならサインアップ)
- SettingsのAPI tokensから、webapiロールが付くトークンを発行
- 発行したトークンを
SEMGREP_APP_TOKEN環境変数として渡す
export SEMGREP_APP_TOKEN=<token>MCP設定JSONで渡す場合は、サーバー定義のenvにSEMGREP_APP_TOKENを追加します。トークンなしでもローカルスキャン系のツールは動きますが、クラウド側の検出結果を返すsemgrep_findingsには、OAuthログインかwebapiロール付きのAPIトークンが必要です。semgrep_whoamiはAPIトークンでは使えず、OAuth接続時のJWTを使うため、stdio接続では登録されません。
APIトークンやサービスアカウントの共有は推奨されていません。失効の影響が全員に及び、共有の資格情報は1ユーザーとして扱われてレート制限にかかるためです。開発者ごとに個別に認証する運用になります。
よくあるつまずき
古いuvx semgrep-mcpの手順しか出てこない
semgrep/mcpリポジトリのREADMEにあったuvx semgrep-mcpやsemgrep-mcp --helpはアーカイブ前の手順です。現行はSemgrep CLI本体に統合されたsemgrep mcpサブコマンドに置き換わっています。検索結果で古いページに当たった場合は、現行の導入手順であるclaude plugin install semgrep@claude-plugins-officialを使います。
VS CodeやCopilotでフックが効かない
Codex・VS Code・Copilotの統合は、書き込み後に自動でスキャンするhookを持たず、エージェントがMCPツールを明示的に呼んだときだけ動作します。自動スキャンを期待する場合はClaude CodeかCursor、あるいはWindsurfのpost_write_codeフックの利用が前提になります。
semgrep_findingsが結果を返さない・エラーになる
トークン未設定や、webapiロールの無いAPIトークンではエラーになります。エラーが出ないのに空のときは、既定の絞り込み(Openの検出・現在のリポジトリ・primary branch)に当たる検出が無い可能性があります。ローカルスキャンのツール(semgrep_scan等)はトークンなしでも動作します。
まとめ
まずは既定のリモートプラグインで始め、CIの指摘とずれるときや組織のPoliciesを反映したいときにローカルCLI経由へ移す、という順序になります。自動スキャンが要らず素のツールだけ使うなら、claude mcp addで足ります。Claude Code向けMCP追加の一般手順はClaude Code MCP設定ガイドで扱っています。