Overview

This MCP (Model Context Protocol) server screens people and organizations against global sanctions lists — including OFAC, SDN, UN, and other configured sources. It exposes a lightweight HTTP interface compatible with MCP-style model interactions so you can either submit free-text prompts for name screening or upload documents (PDF, DOCX, TXT) to be parsed and checked. The server returns structured matches with metadata such as matched list, confidence, and source records.

Sanctions screening is a common compliance task across banking, payments, and KYC workflows. Running a dedicated MCP server for screening enables programmatic, repeatable checks from applications, chatbots, or data pipelines. The server is designed for developers: simple install, configurable list sources, and JSON responses consumable by downstream services.

Features

Screen names and documents against OFAC, SDN, UN and other configured global sanctions lists
Prompt-based screening for interactive or API-driven checks
Document upload and automatic text extraction (PDF, DOCX, TXT)
Configurable sanctions sources and refresh scheduling
JSON responses with match score, matched record details, and provenance links
Simple HTTP API that integrates with MCP-style workflows
Docker-ready and configurable with environment variables

Installation / Configuration

Requirements: Node.js 18+ (or run via Docker). Clone the repository and install dependencies:

git clone https://github.com/madupay/mcp-sanctions.git
cd mcp-sanctions
npm install

Basic environment variables (examples):

# Server
PORT=8080

# Where to store downloaded sanctions lists
SANCTIONS_DATA_DIR=/var/lib/mcp-sanctions/data

# Which sources to enable (comma-separated): ofac,sdn,un,opensanctions
SANCTIONS_SOURCES=ofac,sdn,un

# Schedule to refresh lists (cron-like or interval in minutes)
SANCTIONS_REFRESH_MINUTES=1440

Start the server:

npm run start
# or for development
npm run dev

Docker usage:

# Build image
docker build -t mcp-sanctions:latest .

# Run with mounted data directory and env
docker run -d \
  -p 8080:8080 \
  -v /var/lib/mcp-sanctions/data:/data \
  -e SANCTIONS_SOURCES=ofac,sdn,un \
  -e SANCTIONS_REFRESH_MINUTES=1440 \
  mcp-sanctions:latest

The server will download and cache configured sanctions lists on first run (or according to refresh schedule). Check logs for data fetch progress.

Available Tools / Resources

GitHub repository: https://github.com/madupay/mcp-sanctions
Common sanctions sources typically supported:
- OFAC SDN (US Treasury) — https://home.treasury.gov
- United Nations sanctions lists — https://www.un.org
- OpenSanctions (aggregated global lists) — https://opensanctions.org
Example client snippets (see Use Cases)
Health and metrics endpoints: /health, /metrics

API Overview

Common endpoints (example):

POST /screen — prompt-based name screening
- Request: JSON { “query”: “name or company”, “threshold”: 0.7 }
- Response: JSON array of matches with score and source
POST /screen/upload — file upload to extract and screen text
- Accepts multipart/form-data with file field document
GET /health — basic health check
GET /lists — current loaded lists and metadata (last refresh, source URLs)

Example response shape:

{
  "query": "John Doe",
  "matches": [
    {
      "name": "JOHN DOE",
      "list": "OFAC SDN",
      "id": "sdn-12345",
      "score": 0.92,
      "source_url": "https://..."
    }
  ]
}

Use Cases

Interactive chatbot screening
- A compliance chatbot receives a user message “Is Acme Trading Ltd on any sanctions lists?” Forward the message to POST /screen with the query and parse returned matches to inform the operator or trigger a workflow.
Example curl:
```
curl -X POST http://localhost:8080/screen \
  -H "Content-Type: application/json" \
  -d '{"query":"Acme Trading Ltd","threshold":0.75}'
```
Onboarding automation (document upload)
- Upload a customer’s incorporation document or scanned ID to /screen/upload. The server extracts text, runs name extraction, and screens detected entities. Use this inside an onboarding pipeline to block or flag high-confidence matches.
Example curl (file upload):
```
curl -X POST http://localhost:8080/screen/upload \
  -F "document=@/path/to/file.pdf"
```
Batch reconciliation
- Periodically run a job that submits CSV rows (names and entity IDs) through the /screen endpoint, ingest results, and update your case management system when score >= threshold.
Audit and provenance
- Use GET /lists to show which list versions were used for a screening decision (essential for compliance audit trails).

Best Practices

Set an appropriate confidence threshold for your risk appetite; consider human review for scores in a middle range.
Regularly refresh sanctions lists; configure SANCTIONS_REFRESH_MINUTES according to your compliance policy.
Log screening requests and corresponding list metadata (last refresh timestamp) to support audits.
Treat screening results as indicators, not definitive legal determinations; route positive or uncertain results into a manual review process.

For full implementation details, API reference, and examples, see the repository: https://github.com/madupay/mcp-sanctions.

MCP Server Sanctions Screening OFAC SDN UN