About opensanctions-mcp
opensanctions-mcp connects OpenSanctions sanctions and politically exposed person (PEP) data to MCP for AI agents screening people and companies. It supports entity search, matching, and relationship investigations, and can also connect to a self-hosted yente instance.
Key features
- 01Search entities by name or keyword
- 02Screen people and companies for sanctions and PEP risks
- 03Retrieve entity details and relationships
- 04Inspect datasets and their details
- 05Run a compliance investigation in one call
Use cases
- 01Check whether a person appears on sanctions lists
- 02Screen companies and related entities
- 03Review sanctions and PEP datasets
- 04Investigate entity relationships in structured results
MCP support
The MCP server exposes OpenSanctions tools for entity search, screening, details, and datasets. Its API URL can point to the hosted API or a self-hosted yente instance.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
npx -y opensanctions-mcpOPENSANCTIONS_API_KEYSecretOpenSanctions API key. Get a free key at https://www.opensanctions.org/api/OPENSANCTIONS_API_URLAPI URL. Defaults to https://api.opensanctions.org. Set to your self-hosted yente URL if applicable.Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.
Tools
6Saved tool list · updated 3w ago
| Parameter | Type | Required | Description |
|---|---|---|---|
| limit | number | No | Max results to return (default: 20) |
| query | string | Yes | Name or keyword to search for |
| schema | string | No | Filter by entity type: "Person", "Company", "LegalEntity", "Organization" |
| dataset | string | No | Screen against a specific dataset (e.g. "us_ofac_sdn"). Defaults to all datasets. |
Details
From the project READMEopensanctions-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
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.