mcp-yoshi

MCPの通信、ちゃんと見てヨシッ！

MCP (Model Context Protocol) ツール通信のリアルタイムセキュリティフィルター。 Claude Code の hook として動作し、MCPツールの送受信データを検査して安全性を判定します。

なぜ必要か

• MCPツールの説明文は97%が不十分、13%が実装と不一致（研究論文）
• 既存ツール（mcp-scan, mcp-drift-detector）は静的チェック・事前検査のみ
• リアルタイムの通信フィルターが存在しなかった

mcp-yoshi は通信の瞬間にデータを検査し、問題があれば即座にブロックまたは警告します。

機能

アウトバウンドチェック（送信データ → MCPサーバー）

| ID | チェック | 検出対象 | |----|---------|---------| | OUT-001 | API Key Pattern | AWS, OpenAI, GitHub, Slack, Google, Stripe 等のAPIキー | | OUT-002 | Private Key | RSA/EC/DSA/OPENSSH秘密鍵 | | OUT-003 | High Entropy String | 32文字以上の高ランダム文字列 | | OUT-004 | Env Value Pattern | PASSWORD, SECRET, TOKEN 等の環境変数値 | | OUT-005 | PII Pattern | メールアドレス、電話番号、クレジットカード番号 | | OUT-006 | Large Payload | リクエストペイロードが50KB超（大量データ送信） | | OUT-007 | Path Traversal | /etc/passwd, ~/.ssh/, C:\Windows\ 等のセンシティブパス |

インバウンドチェック（MCPサーバー → 受信データ）

| ID | チェック | 検出対象 | |----|---------|---------| | IN-001 | Prompt Injection | "ignore previous instructions" 等の指示上書き | | IN-002 | Shell Command Embedding | $(...), ; rm, \| bash 等のコマンド注入 | | IN-003 | Suspicious URL / SSRF | javascript:, 短縮URL, 内部ネットワーク, クラウドメタデータ(169.254.169.254等) | | IN-004 | Script Injection | <script>, eval(), document.cookie 等 | | IN-005 | Tool Definition Tampering | ツール説明文に埋め込まれた隠し指示（12パターン） | | IN-006 | ASCII Smuggling | 不可視Unicode文字（U+E0000台Tags Block, Zero-Width文字） | | IN-007 | Base64 Encoded Payload | Base64デコード後に既存パターンで再検出 | | IN-008 | Response Size Limit | レスポンスが200KB超（コンテキストウィンドウ毒盛対策） | | IN-009 | Hidden Fields | _hidden, $meta 等の未宣言フィールド | | IN-010 | Elicitation Abuse | 認証情報要求・コマンド実行誘導をBLOCK |

レート制限（通信パターン）

| ID | チェック | 検出対象 | |----|---------|---------| | RATE-001 | Rapid Fire Detection | 同一ツールが60秒以内に10回以上呼び出された場合にWARN |

Rug Pull検出（ツール定義の改竄検知）

| ID | チェック | 検出対象 | |----|---------|---------| | RUG-001 | Tool Definition Changed | ツール定義のSHA-256ハッシュ変更を検知 |

初回呼び出し時にツール定義のハッシュを記録し、以降の呼び出しで変更があればWARNを発生させます。ハッシュは ~/.mcp-yoshi/tool-hashes.json に永続化されるため、セッションを跨いだ検出が可能です。

NFKC正規化（難読化対策）

全てのインバウンド/アウトバウンドチェックの前段でNFKC正規化を適用します。全角文字（ｉｇｎｏｒｅ → ignore）やUnicode互換文字による難読化を透過的に検出します。

3段階判定

| 判定 | 動作 | |------|------| | PASS | 問題なし。そのまま実行 | | WARN | 警告をClaudeのコンテキストに追加。実行は継続 | | BLOCK | ツール実行を阻止（送信時）/ 警告表示（受信時） |

インストール

npm install -g mcp-yoshi

セットアップ

# Claude Code の settings.json に hook 設定を自動追加
mcp-yoshi init

# プロジェクト単位で設定する場合
mcp-yoshi init --project

これにより、以下の hook が自動設定されます：

• PreToolUse: mcp__.* にマッチ → アウトバウンドチェック
• PostToolUse: mcp__.* にマッチ → インバウンドチェック

使い方

セットアップ後は自動的に動作します。MCPツールが呼ばれるたびにチェックが実行されます。

ログ確認

# 直近20件のログを表示
mcp-yoshi logs

# 直近50件のWARN以上のみ表示
mcp-yoshi logs --tail 50 --level warn

# BLOCK のみ表示
mcp-yoshi logs --level block

統計レポート

# 過去7日間の検出統計を表示
mcp-yoshi stats

# 過去30日間
mcp-yoshi stats --days 30

設定確認

mcp-yoshi config

Allowlist（信頼済みサーバー）

特定のMCPサーバーを信頼済みとして登録し、チェックをスキップできます。 ユーザー責任での運用となりますが、ログ記録は継続されます（severity: SKIPPED）。

# サーバーを allowlist に追加（理由必須推奨）
mcp-yoshi allow memory --reason "社内ナレッジグラフ、信頼済み"

# allowlist 一覧
mcp-yoshi allow --list

# allowlist から削除
mcp-yoshi allow --remove memory

~/.mcp-yoshi/config.json で直接設定することもできます：

{
  "allowlist": [
    { "server": "memory", "reason": "社内ナレッジグラフ", "addedAt": "2026-03-12T00:00:00.000Z" }
  ]
}

設定カスタマイズ

~/.mcp-yoshi/config.json を作成して設定を上書きできます。

{
  "logLevel": "warn",
  "checks": {
    "outbound": {
      "highEntropy": false
    }
  },
  "servers": {
    "*": { "enabled": true },
    "memory": { "enabled": true },
    "trusted-server": { "enabled": false }
  },
  "severity": {
    "WARN": ["highEntropy", "pii", "suspiciousUrls", "base64Payload", "largePayload", "responseSizeLimit", "hiddenFields", "rapidFire"],
    "BLOCK": ["apiKeys", "privateKeys", "promptInjection", "shellCommands", "scriptInjection", "toolTampering", "envValues", "asciiSmuggling", "pathTraversal", "elicitationAbuse"]
  }
}

MCPサーバー別の設定

servers セクションでMCPサーバーごとにフィルターのON/OFFとチェック項目を制御できます。

{
  "servers": {
    "*": { "enabled": true },
    "trusted-internal": { "enabled": false },
    "external-api": {
      "enabled": true,
      "checks": {
        "outbound": { "pii": false },
        "inbound": { "promptInjection": true }
      }
    }
  }
}

| キー | 説明 | |------|------| | "*" | デフォルト設定（未定義のサーバーに適用） | | "<server名>" | mcp__<server名>__* のツールに適用 |

• enabled: false → そのサーバーのチェックを完全スキップ
• checks → グローバル設定をサーバー単位でオーバーライド

設定項目

| 項目 | デフォルト | 説明 | |------|-----------|------| | logDir | ~/.mcp-yoshi/logs | ログ出力先 | | logLevel | info | info: 全記録, warn: WARN以上, none: 記録なし | | checks.outbound.* | true | 各アウトバウンドチェックの有効/無効 | | checks.inbound.* | true | 各インバウンドチェックの有効/無効 | | servers | {"*": {"enabled": true}} | サーバー別ON/OFF | | severity.WARN | ["highEntropy", "pii", "suspiciousUrls", "base64Payload"] | WARN判定するチェックID | | severity.BLOCK | ["apiKeys", "privateKeys", "promptInjection", ..., "asciiSmuggling"] | BLOCK判定するチェックID |

アンインストール

# hook 設定を削除
mcp-yoshi uninstall

# パッケージ削除
npm uninstall -g mcp-yoshi

既存ツールとの違い

| ツール | タイミング | 対象 | |--------|----------|------| | mcp-scan | 事前（静的チェック） | ツール定義の安全性 | | mcp-drift-detector | 定期（変更検出） | ツール定義の改竄 | | mcp-yoshi | リアルタイム（通信時） | 送受信データの安全性 |

注意事項

• パフォーマンス: 全てのMCPツール呼び出しでhookが実行されるため、MCP操作に若干の遅延（数十ms程度）が発生します。気になる場合は logLevel: "warn" に変更するか、信頼済みサーバーを enabled: false に設定してください
• 誤検出（False Positive）: 高エントロピー文字列やPIIパターンは正規のデータにもマッチすることがあります。頻繁に誤検出する場合は該当チェックを無効にするか、severity設定でWARNに下げてください
• 検出限界: 正規表現ベースのパターンマッチとNFKC正規化による検出です。高度に難読化された攻撃や未知のパターンは検出できない場合があります。他のセキュリティツール（mcp-scan等）との併用を推奨します
• Rug Pull検出: ツール定義ハッシュは ~/.mcp-yoshi/tool-hashes.json に永続化されます。ファイルが破損した場合は自動的に空の状態から再開します

ライセンス

MIT