Enrichment MCP Server

エンリッチメント MCP サーバー

提供されたオブザーバブルに基づいてエンリッチメントを実行する、Model Context Protocol（MCP）サーバーです。設定されたサービスと提供されたオブザーバブルの組み合わせによって、利用するエンリッチメントサービスが決まります。

このツールは、一般的なサービス（VirusTotal、Hybrid Analysis など）を使用して、サードパーティーによるエンリッチメントを実行するシンプルな実装を提供します。

このプロジェクトは、本番環境で使用されたことはありません。

機能

この enrichment-mcp MCP サーバーの実装では、次のツールを公開しています。

• observable-lookup - 汎用エンドポイントです。指定されたオブザーバブルを検査し、適切なツールに振り分けます。
• lookup-ipaddress - 指定された IPv4 アドレスのエンリッチメントを実行します。
• lookup-domain - 指定されたドメイン名のエンリッチメントを実行します。
• lookup-url - 指定された URL（場合によってはドメイン名）のエンリッチメントを実行します。
• lookup-email - 指定されたメールアドレスのエンリッチメントを実行します。

判定されたオブザーバブルの種類に問題がある場合は、issue を作成してください。現在実装されている正規表現パターンを更新することもできます。

対応サービス

現在、次のサービスとオブザーバブルの種類に対応しています。

ご提案がある場合や、別のサービスを追加すべきだと思われる場合は、issue またはプルリクエストを作成してください。

名前	API キーが必要	IP に対応	ドメインに対応	URL に対応	メールに対応
VirusTotal	はい	はい	はい	はい	いいえ
HybridAnalysis	はい	はい	はい	はい	いいえ
AlienVault	はい	はい	はい	はい	いいえ
Shodan	はい	はい	はい	はい	いいえ
Urlscan.io	はい	はい	はい	はい	いいえ
AbuseIPDB	はい	はい	いいえ	いいえ	いいえ
HaveIBeenPwned	はい	いいえ	いいえ	いいえ	はい

要件

この MCP サービスでは、オブザーバブルの検索に使用するサードパーティーのエンリッチメントサービスを指定するカスタム設定ファイルを実装しています。

現時点では開発／テスト専用のため、ローカルの Mac／システムで実行する最も簡単な方法は次のとおりです。

uv run --env-file .env server.py

付属のテンプレート .env.exampl を使い、シークレットを含む新しい .env ファイルを作成する必要があります。

config.yaml

このプロジェクトではカスタム設定ファイルを使用します。比較的わかりやすい内容になっています。

まず、付属の config.yaml.example 設定ファイルをコピーし、このサービスを使用する前に .example 拡張子を削除してください。

この設定ファイルには、主に server と enrichments の2つのセクションがあります。

デフォルトでは、サポートされているすべてのサービスが、現在実装されているエンリッチメントアクションの種類に対応付けられています。現在、実際に利用できるエンリッチメントアクションの種類は lookups のみですが、今後ほかの種類も実装される可能性があります。

lookups の下には、サポートされているさまざまなエンリッチメントの種類があります。

各サービスには apikey というキーと、そのサービスの API キーの値を設定できますが、そうしないことをおすすめします。

このキーの値は config.yaml.example に直接設定できますが、.env を使用する方法をおすすめします。

NOTE：このサービスを実装する際は、シークレットを環境変数として設定することを強くおすすめします。シークレットを保存するのはやめましょう。

このサービスがこれらの変数を検出するには、特定の形式にする必要があります。現在サポートされている変数の一覧は以下のとおりです。

• ENRICHMENT_MCP_VIRUSTOTAL_KEY
• ENRICHMENT_MCP_HYBRIDANALYSIS_KEY
• ENRICHMENT_MCP_ALIENVAULT_KEY
• ENRICHMENT_MCP_SHODAN_KEY
• ENRICHMENT_MCP_URLSCAN_KEY
• ENRICHMENT_MCP_HIBP_KEY

サーバーの設定

ここで設定できる項目は最小限です。主にサンドボックス化とテストを目的としていますが、通常、このサービスを動作させるために設定を変更する必要はありません。

server:
  host: 0.0.0.0 # the host address
  port: 8000 # the port
  debug: false # whether to enable debug logging
  log_level: INFO # the default logging level

エンリッチメントの設定

設定ファイルでは、各エンリッチメントを enrichments キーの下に記述します。また、実行できるエンリッチメントの種類ごとに分けています。つまり、現在の実装では lookups という単一のアクションの種類のみですが、将来的には scans や queries などに拡張できます。

これらの上位アクションの下に、オブザーバブルの種類と、その種類をサポートするサービスの一覧を記述します。現在サポートされているオブザーバブルの種類は以下のとおりです。

• ipaddress - IPv4 アドレス
• domain - ドメインまたはネットロケーション
• url - スキーマなどを含む完全修飾 URL
• email - 標準的なメールアドレス

以下の種類もサポートしていますが、現在は実装されていません。

• md5 - ファイルの MD5 ハッシュ
• sha1 - ファイルの SHA1 ハッシュ
• sha256 - ファイルの SHA256 ハッシュ

各サービスには name と template が必要です。apikey フィールドも指定できますが、環境変数を使用することをおすすめします。

プロンプトテンプレート

各サービスとオブザーバブルの種類には、それぞれ独自のテンプレートを設定できます。テンプレートは templates ディレクトリに置き、すべてのテンプレートをこのディレクトリに配置する必要があります。

定義されている各サービスには、jinja2 テンプレートを使用したプロンプトテンプレートがあります。必要に応じて変更できますが、ファイル名の形式は変更しないでください。

これらのファイル名には、以下のパターンを使用してください。

{service.name}.{enrichment.type}.jinja2

また、テンプレート自体にレスポンスオブジェクトの正しいフィールドが含まれていることを確認してください。そうでない場合、エラーが発生します。

以下は、Enrich this IP 91.195.240.94 というプロンプトにエラーが混在した場合の出力例です。

{
    "virustotal": "error occurred looking up ip 91.195.240.94 in virustotal",
    "alienvault": "Service: alienvault\nIPAddress: \nReputation Score: 0\nTotal Votes: ",
    "shodan": "Service: shodan\nIPAddress: 91.195.240.94\nLast Analysis Results: 2025-04-25T21:02:52.644602\n\nTags\n\n\nAdditional information includes:\n\n* Latitude: 48.13743\n* Longitude: 11.57549\n* ASN: AS47846\n* Domains: ["servervps.net"]",
    "hybridanalysis": "error occurred looking up ip 91.195.240.94 in hybridanalysis",
    "urlscan": "Service: urlscan\nResult: https://urlscan.io/api/v1/result/01966efe-c8fa-74a4-bfc0-1ed479838e85/\n\nStats\n\n* uniqIPs - 6\n\n* uniqCountries - 2\n\n* dataLength - 432561\n\n* encodedDataLength - 218606\n\n* requests - 14\n\n\nPage\n* country - DE\n* server - Parking/1.0\n* ip - 91.195.240.94\n* mimeType - text/html\n* title - wearab.org\xa0-\xa0Informationen zum Thema wearab.\n* url - https://login.wearab.org/\n* tlsValidDays - 364\n* tlsAgeDays - 0\n* tlsValidFrom - 2025-04-25T00:00:00.000Z\n* domain - login.wearab.org\n* apexDomain - wearab.org\n* asnname - SEDO-AS SEDO GmbH, DE\n* asn - AS47846\n* tlsIssuer - Encryption Everywhere DV TLS CA - G2\n* status - 200\n",
    "abuseipdb": "Service: abuseripdb\nIPAddress: 91.195.240.94\nLast Analysis Result: 2025-03-30T14:04:45+00:00\nScore: 7\nUsage: Data Center/Web Hosting/Transit\nIs Tor: False\nIs Whitelisted: False\nISP: Sedo Domain Parking"
}

使い方

ビルド済みサーバーの使用方法については、こちらの手順を参照してください：https://modelcontextprotocol.io/quickstart/user

• Claude for Desktop をダウンロードする
• uv をインストールする

curl -LsSf https://astral.sh/uv/install.sh | sh

• このリポジトリをダウンロードし、Claude for Desktop の設定に追加する
  • Claude for Desktop > Settings > Developer > Edit Config

次の場所に設定ファイルが作成されます。

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

設定ファイルを任意のテキストエディターで開き、内容を次のように置き換えてください。

{
	"mcpServers": {
		"enrichment-mcp": {
			"command": "/ABSOLUTE/PATH/TO/PARENT/FOLDER/uv",
			"args": [
				"--directory",
				"/ABSOLUTE/PATH/TO/CLONED/REPOSITORY/enrichment-mcp",
				"run",
				"server.py"
			]
		}
    }
}

4. Claude for Desktop を再起動する

これでチャットバーに2つのアイコンが表示されます。ハンマーのアイコンには利用可能なツールが表示され、接続アイコンには定義されたプロンプトと必要な入力が表示されます。

設計

このサーバーの構築中、MCP とともに、astral uv についても学んでいました。間違いなく設計を過剰にしすぎましたが、楽しかったです。このコードの一部は将来ほかの用途でも使う予定があったため、その点も考慮して設計しました（その件については、また後日お知らせします）。

また、返されるプロンプトや結果をより適切に管理でき、将来のユースケースにも対応できるよう、Jinja2 テンプレートを採用しました。

フィードバック、改善案、機能リクエストをぜひお寄せください。すべて歓迎します。

貢献

貢献を歓迎します！お気軽にプルリクエストを送信してください。

免責事項

このツールは、教育および許可を得たテストのみを目的としています。