Enrichment MCP Server

Created By

MSAdministrator8 months ago

A Model Context Protocol server for enriching data from multiple security products

Content

Enrichment MCP Server

This project is a Model Context Protocol (MCP) server for performing enrichment given a provided observable. The combination of configured services and the provided observable(s) will determine which enrichment services to call.

This tool provides a simple MCP server implementation to perform third-party enrichment using common services (e.g. VirusTotal, Hybrid Analysis, etc.) utilizing the security-cli python package to perform enrichment/communicate with different services.

MCP Server

This implementation of the enrichment-mcp MCP server exposes the following tools.

lookup-observable - A generic endpoint which examines and routes the given observable to the correct tool.

Supported Services

The following services and observable types are currently supported:

If you have any suggestions or believe another service should be implemented, please create an issue or pull request!

Name	API Key Required	Supports IP	Supports Domain	Supports URL	Supports Email
VirusTotal	Yes	Yes	Yes	Yes	No
HybridAnalysis	Yes	Yes	Yes	Yes	No
AlienVault	Yes	Yes	Yes	Yes	No
Shodan	Yes	Yes	Yes	Yes	No
Urlscan.io	Yes	Yes	Yes	Yes	No
AbuseIPDB	Yes	Yes	No	No	No
HaveIBeenPwned	Yes	No	No	No	Yes

Requirements

This MCP service uses security-cli and a custom config.yaml.example file to determine which third-party enrichment services are supported for observable lookups.

The easiest way to run this on a local mac/system is:

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

This requires that you use the provided template .env.example and create a new .env file with your secrets.

NOTE: Please review the documentation for security-cli for information on configuring different services. The default will suffice for most use cases.

Environmental Variables

NOTE: It is highly recommended to set secrets as environmental variables when implementing this service. Stop storing secrets silly goose.

In order for the security-cli package to discover these variables, they must be in a specific format. Below is the list of currently supported variables:

ENRICHMENT_MCP_VIRUSTOTAL_KEY
ENRICHMENT_MCP_HYBRIDANALYSIS_KEY
ENRICHMENT_MCP_ALIENVAULT_KEY
ENRICHMENT_MCP_SHODAN_KEY
ENRICHMENT_MCP_URLSCAN_KEY
ENRICHMENT_MCP_ABUSEIPDB_KEY
ENRICHMENT_MCP_HIBP_KEY

Enrichments Configuration

Each enrichment service is defined in the securiy-cli config file. Additionally, I have broken out the different types of enrichment that can be performed. This means, in the current implementation, we have a single action type called enrich but in the future this can be expanded for things like scans or queries etc.

Underneath these high-level actions, we list out the observable type followed by a list of services that support that type. The currently supported observable types are:

ipaddress - ipv4 addresses
domain - A domain or netloc
url - A fully qualified URL with schema, etc.
email - A standard email address

We also support these types but they are currently not implemented:

md5 - A file MD5 hash
sha1 - A file SHA1 hash
sha256 - A file SHA256 hash

Each service must have a name and a template. The apikey field can be provided but we recommend to use environmental variables.

Prompt Templates

Each service and observable type can have it's own response template. These reside in the security-cli templates directory and all templates are expected to exist here.

Each service defined has a prompt template using jinja2 templates. You can modify these are needed, but the format of the filename must remain the same.

These files have the following filename pattern.

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

Ensure that the response object has the correct fields in the template itself or you will receive an error.

Below is an example output for a prompt of Enrich this IP 91.195.240.94 with some errors mixed in:

{
    "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"
}

MCP Server Usage

For using a pre-built server, instructions from here: https://modelcontextprotocol.io/quickstart/user

Download Claude for Desktop
Install uv

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

Download this repo and add to Claude for Desktop config
- Claude for Desktop > Settings > Developer > Edit Config

You can copy the provided .desktop_config.example.json file

If you want to create it yourself, these are the paths for Claude Desktop.

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

Open up the configuration file in any text editor. Replace the file contents with this:

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

Relaunch Claude for Desktop

You should now see two icons in the chat bar, a hammer which shows the tools available and a connection icon which shows the prompt defined and the input required.