opensanctions-mcp

MCP server for sanctions screening and PEP checks via the OpenSanctions API.

Lets AI agents (Claude, Cursor, Windsurf, GPT) screen persons and companies against 320+ sanctions and PEP lists from OFAC, EU, UN, UK HMT, and more.

Disclaimer: This tool provides informational data only. It is not legal or compliance advice. Always verify matches with official sources before taking action.

Quick Start

Add to your MCP client config:

{
  "mcpServers": {
    "opensanctions": {
      "command": "npx",
      "args": ["-y", "opensanctions-mcp"],
      "env": {
        "OPENSANCTIONS_API_KEY": "your-key-here"
      }
    }
  }
}

Get a free API key at opensanctions.org/api.

Where to add this config

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)
• Cursor: Settings > MCP Servers
• Windsurf: ~/.windsurf/config.json

Tools

search_entities

Search the OpenSanctions database by name or keyword.

"Search for entities named Viktor Bout"
"Find companies related to Iran sanctions"

match_entity

Screen a person or company against sanctions and PEP lists using structured properties. This is the primary screening tool.

"Screen Viktor Bout, born 1967-01-13, Russian national, against sanctions lists"
"Check if Acme Corp is on any EU sanctions list"

get_entity

Fetch complete details for a specific entity, including relationships to other entities (companies, associates, family members).

"Get full details for entity NK-2Ciy8EG7jz1YHMGCxYLb25"

list_datasets

List available sanctions and PEP datasets. No API key required.

"What sanctions lists are available?"
"Show me EU-related datasets"

get_dataset

Get details about a specific dataset (publisher, entity count, last updated). No API key required.

"Tell me about the OFAC SDN list"

investigate_entity

Run a full compliance investigation in one call: match, fetch details, map relationships, and return structured data.

"Investigate Viktor Bout for sanctions exposure"
"Run a compliance check on Acme Corp, jurisdiction Belgium"

Configuration

| Environment Variable | Required | Default | Description | |---|---|---|---| | OPENSANCTIONS_API_KEY | Yes* | — | API key for the hosted OpenSanctions API. Get one at opensanctions.org/api. | | OPENSANCTIONS_API_URL | No | https://api.opensanctions.org | API URL. Set to your self-hosted yente instance. | | OPENSANCTIONS_DATASET | No | default | Dataset to screen against. default includes all 320+ sources. | | OPENSANCTIONS_MAX_RETRIES | No | 3 | Max retries for failed API calls. | | DEBUG | No | — | Set to any value to enable debug logging. |

*Not required for list_datasets, get_dataset, or when using a self-hosted yente instance without auth.

Self-hosted yente

If you run your own yente instance, point the server at it:

{
  "mcpServers": {
    "opensanctions": {
      "command": "npx",
      "args": ["-y", "opensanctions-mcp"],
      "env": {
        "OPENSANCTIONS_API_URL": "http://localhost:8000"
      }
    }
  }
}

No API key needed for self-hosted yente.

Development

git clone https://github.com/scka-de/opensanctions-mcp.git
cd opensanctions-mcp
npm install
npm test          # run tests (fixtures, no API key needed)
npm run build     # compile to dist/
npm run dev       # run in dev mode
npm run lint      # check code style

License

MIT