sanctions-screening-mcp-server

<div align="center">
  <h1>@cyanheads/sanctions-screening-mcp-server</h1>
  <p><b>Screen names against the consolidated OFAC, EU, UK, and UN sanctions lists and resolve legal entities against GLEIF, fuzzy-matched offline over a local SQLite + FTS5 mirror. A screening aid, not a compliance determination.</b>
  <div>6 Tools • 3 Resources • 1 Prompt</div>
  </p>
</div>

<div align="center">

[![Version](https://img.shields.io/badge/Version-0.1.2-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3-blueviolet.svg?style=flat-square)](https://bun.sh/)

[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/sanctions-screening-mcp-server/releases/latest/download/sanctions-screening-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=sanctions-screening-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvc2FuY3Rpb25zLXNjcmVlbmluZy1tY3Atc2VydmVyIl19) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22sanctions-screening-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fsanctions-screening-mcp-server%22%5D%7D)

[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)

</div>

<div align="center">

**Public Hosted Server:** [https://sanctions-screening.caseyjhand.com/mcp](https://sanctions-screening.caseyjhand.com/mcp)

</div>

---

> [!IMPORTANT]
> **This is a screening aid, not legal or compliance certification.** Every tool returns *potential matches* with a transparent score and source provenance — never a verdict. A hit means "review this candidate against the official source"; an empty result never means "cleared." Real sanctions compliance is a legal process — it requires human review and a qualified compliance determination. This server feeds that process; it does not perform it, and its output is not a compliance record.

## Overview

`sanctions-screening-mcp-server` turns the world's open sanctions data plus the global legal-entity registry into one screening-and-resolution workflow, answered offline and fuzzy-matched. It screens a name against the consolidated US (OFAC), EU, UK, and UN sanctions lists at once, and resolves legal entities against the GLEIF Legal Entity Identifier (LEI) database with corporate-ownership tracing.

All sources are bulk-downloadable, keyless, and clear for redistribution. The server mirrors them to a local SQLite + FTS5 index and serves matches from that mirror — no live API key, no per-request rate limit on the hot path. The agent sees screening verbs (`screen_name`, `resolve_entity`, `trace_ownership`); which list answered a query surfaces only as provenance on each hit.

The matching model is transparent by design: strict token matching first (exact-normalized, then all-tokens-present via FTS5), with a scored Jaro-Winkler + phonetic fuzzy fallback. Approximate hits carry the **raw Jaro-Winkler similarity (0–1)** — a real measurement, never a fabricated "confidence percentage."

## Tools

Six tools organized around two workflows — screen a name against the watchlists, and resolve a legal entity to its global identifier and ownership graph:

| Tool | Description |
|:---|:---|
| `sanctions_screen_name` | Screen a name (person, company, vessel, aircraft) against all loaded watchlists at once — OFAC SDN + Consolidated, EU, UK, UN — alias- and fuzzy-aware. Returns scored potential matches with source list, program, designation date, and the matched alias. |
| `sanctions_get_designation` | Fetch the full record for one sanctions designation by source list + entry ID: all aliases, identifiers, addresses, dates/places of birth, nationalities, program, legal basis, and designation date. |
| `sanctions_resolve_entity` | Resolve a company / organization name (+ optional jurisdiction) to ranked candidate GLEIF LEIs. Turns a free-text counterparty name into a stable global identifier. |
| `sanctions_get_entity` | Fetch the full GLEIF Level 1 record for one LEI — legal name, trading names, addresses, registration status, jurisdiction — plus a sanctions cross-reference screened on the legal name. |
| `sanctions_trace_ownership` | Trace the GLEIF Level 2 corporate-ownership graph for an LEI (parents and/or children, BFS to a bounded depth), optionally screening every node for beneficial-ownership screening. |
| `sanctions_list_sources` | List the loaded watchlists and GLEIF datasets with record counts, source URLs, licenses, and the mirror's readiness and as-of timestamps. |

### `sanctions_screen_name`

The 80% entry point — "is this entity on a watchlist?"

- Fans out across all four sanctions lists (OFAC SDN + Consolidated, EU, UK, UN) in one call; the source surfaces only as provenance per hit
- Alias-aware: matches against every published primary name, a.k.a., and f.k.a., not just the canonical name
- Strict mode (default): exact-normalized equality, then all-tokens-present via FTS5 — handles word-order swaps and missing interior words with no fuzzy library
- Fuzzy mode (opt-in, or automatic when strict finds nothing): adds Jaro-Winkler similarity and Double-Metaphone phonetic matching for transliteration-class misses
- Hits labeled `exact` / `strong` / `approximate`; approximate hits carry the raw Jaro-Winkler score (0–1)
- Filter by entity type, source list subset, similarity floor (`min_score`), and result limit
- On an empty result, returns guidance on how to broaden — and states explicitly that no match is **not** a clearance

---

### `sanctions_get_designation`

The drill-in after `sanctions_screen_name` surfaces a candidate.

- Full normalized record by `source` + `entry_id` (the `sourceEntryId` from a screen hit)
- All published aliases, structured identifiers (passport / national ID / tax / registration), addresses, dates and places of birth, nationalities, sanctioning program, legal basis, and designation date
- Preserves source sparsity — missing fields mean the source omitted them; the record is never padded with fabricated data

---

### `sanctions_resolve_entity`

The bridge from a free-text counterparty name to a stable LEI that the entity tools key off.

- Resolves a company / organization name to ranked GLEIF LEI candidates
- Optional ISO 3166-1 alpha-2 jurisdiction filter and registration-status filter (`issued` default, `lapsed`, or `any`)
- Same strict-then-fuzzy matching model as name screening; approximate hits carry the raw Jaro-Winkler score
- Matches against legal names and published other/trading names

---

### `sanctions_get_entity`

Who is this legal entity — plus a watchlist cross-reference in the same call.

- Full GLEIF Level 1 record: legal name, other/trading names, legal and headquarters addresses, registration status, jurisdiction, registration authority and ID, last-update date
- Cross-references the entity's legal name against all loaded watchlists (strict match only — auto-fuzzy on a generic legal name would flood the result with single-common-token false positives)
- LEI input is regex-validated (20 chars: 18 alphanumerics + 2 check digits)

---

### `sanctions_trace_ownership`

Beneficial-ownership screening — the cross-source workflow that single-list tools can't do.

- Traverses the GLEIF Level 2 ownership graph breadth-first to a bounded depth (1–5)
- `direction`: walk `parents` (who owns it), `children` (what it owns), or `both`
- Returns nodes (with role and depth) and directed ownership edges with relationship type
- `screen_nodes: true` screens every entity in the graph against all watchlists — "is anyone in this ownership chain sanctioned?"
- Per-node screen is strict-only and reports `screenedNodeCount` / `flaggedNodeCount` so a caller can see coverage at a glance

---

## Resources and prompts

| Type | Name | Description |
|:---|:---|:---|
| Resource | `sanctions://designation/{source}/{entryId}` | One sanctions designation by source + entry ID (URI mirror of `sanctions_get_designation`). |
| Resource | `sanctions://entity/{lei}` | One GLEIF Level 1 entity by LEI (URI mirror of `sanctions_get_entity`'s entity payload, without the screening cross-reference). |
| Resource | `sanctions://sources` | Loaded lists + GLEIF datasets with counts and refresh timestamps (URI mirror of `sanctions_list_sources`). |
| Prompt | `sanctions_vet_counterparty` | Sequences the tools into a full counterparty due-diligence pass: resolve → trace ownership → screen the entity and every beneficial owner → summarize with provenance and the decision-support caveat. |

All resource data is also reachable via the tools, which are the primary path for tool-only MCP clients. The resources are a convenience for resource-capable clients only.

## Source lists

The server aggregates five upstream sources behind the screening surface. All are bulk, keyless, and clear for redistribution.

| Source | Role | License |
|:---|:---|:---|
| **OFAC SDN + Consolidated** (US Treasury) | Primary US sanctions/watchlist — individuals, entities, vessels, aircraft, with a.k.a. aliases | US Government public domain |
| **EU Consolidated Financial Sanctions List** | EU-designated persons and entities | Freely redistributable |
| **UK Sanctions List (UKSL, FCDO)** | UK sanctions targets — person