Enrichment MCP Server

Enrichment 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 或 pull request！

名称	是否需要 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。

默认情况下，所有受支持的服务都映射到当前已实现的 enrichment 操作类型。目前唯一真正实现的 enrichment 操作类型是 lookups，但未来可能会实现其他类型。

在 lookups 下，我们定义了不同的受支持 enrichment 类型。

也就是说，每个服务都可以有一个名为 apikey 的键，并填入该服务的 API 密钥，但请考虑不要这样做。

你可以直接在 config.yaml.example 中设置此键的值，但更推荐使用 .env。

注意：强烈建议在实现此服务时将密钥设为环境变量。别再傻乎乎地存储密钥了。

为了让此服务发现这些变量，它们必须采用特定格式。以下是目前支持的变量列表：

• 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 配置

配置文件中的每项 enrichment 都位于 enrichments 键下。此外，我将可执行的不同 enrichment 类型分别列出。这意味着在当前实现中，我们只有一种操作类型，名为 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

现在，你应该能在聊天栏中看到两个图标：一个锤子图标，用于显示可用工具；另一个连接图标，用于显示已定义的提示词和所需输入。

设计

构建此服务时，我一边学习 Astral 的 uv，一边学习 MCP。我确实把它设计得过于复杂了，不过过程很有趣。我也打算将来复用其中的一些代码，因此也尽量考虑了这一点（后续会有更多介绍）。

此外，我特意改用 Jinja2 模板，这样可以更好地管理返回的提示词和结果，同时也为将来的用例做好准备。

欢迎提出任何反馈、改进建议或功能请求，我很乐意听取。

贡献

欢迎贡献！请随时提交拉取请求。

免责声明

此工具仅用于教育和经授权的测试目的。