Sanctions Screening Mcp Server

io.github.cyanheadsPublished by GitHub account cyanheadsv0.7.0Updated Nov 20, 2026

Screen eleven sanctions/export-control lists; resolve GLEIF entities offline. Screening aid.

VerifiedStreamable HTTPWeb executableFinanceSecurity & MonitoringBusiness & Commerce

Overview

AI-generated overview

Screens names and identifiers against eleven sanctions and export-control lists offline, and resolves GLEIF legal entities and ownership.

What you can do
  • Screen person, company, vessel or aircraft names across all loaded watchlists, with strict and fuzzy matching, paging and per-hit provenance
  • Look up IMO numbers, SWIFT/BIC codes, wallet addresses, passports and national IDs exactly across the same lists
  • Fetch a full designation record by entry ID, published reference number or UN reference number
  • Resolve a company name to ranked GLEIF LEIs, fetch an LEI's Level 1 record with a sanctions cross-reference, and trace parents and children
  • List loaded sources with record counts, licenses, harvest and document dates, and mirror readiness
  • Read designation, entity and source data as resources, and run a counterparty due-diligence prompt
When to use it
Useful when an assistant has to check counterparties, customers, vessels or suppliers against sanctions and export-control lists, or turn a free-text company name into a stable LEI and map its accounting-consolidation parents and children. Suited to due-diligence drafting and research where results are then verified against official sources.
Requirements
Runs as a remote Streamable HTTP endpoint or as a local npm package via npx (Node.js). No API keys: all sources are keyless, and data is served from a local SQLite mirror that must be populated out of band before use. Optional environment variables configure auth mode, HTTP host, port and path, log level, fuzzy score floor, mirror path, refresh cron and input normalization.
Before you install
Results are explicitly a screening aid, not a compliance determination or clearance, and should be verified against official agency lists. Ownership tracing covers GLEIF accounting-consolidation relationships only, never beneficial ownership. Fuzzy and phonetic matches are approximate and bounded by candidate pools, so empty or partial results do not prove absence. The mirror must be refreshed to stay current, and a failed refresh keeps older data.

Installation

In SourceWeft

  1. Open Sanctions Screening Mcp Server in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.cyanheads%2Fsanctions-screening-mcp-server/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "sanctions-screening": {
      "type": "http",
      "url": "https://sanctions-screening.caseyjhand.com/mcp"
    }
  }
}

README

@cyanheads/sanctions-screening-mcp-server

Screen names against eleven OFAC, EU, UK, UN, BIS, and State sanctions and export-control lists and resolve legal entities against GLEIF, matched offline over a local SQLite + FTS5 mirror. A screening aid, not a compliance determination.

7 Tools • 4 Resources • 1 Prompt


Overview

Sanctions and export-control screening over eleven lists plus the GLEIF LEI registry, matched offline against a local mirror. Screen a name or identifier for potential watchlist hits, resolve a company to its LEI, and trace its accounting-consolidation relationships.

Source codesLists
ofac_sdn, ofac_consolidatedOFAC SDN and Consolidated
eu, uk, unEU, UK Sanctions List, UN Security Council
bis_el, bis_dpl, bis_uvl, bis_meuBIS Entity, Denied Persons, Unverified, Military End User
state_dtc, state_acnState ITAR Debarred, Nonproliferation Sanctions

The six BIS/State lists come from trade.gov's keyless Consolidated Screening List (CSL) bulk download. Treasury CSL copies are skipped; direct OFAC provenance and grouping remain unchanged.

[!IMPORTANT] A screening aid, not a compliance determination. Every result is a potential match with a transparent score and source provenance, never a verdict. A hit is a candidate to verify against the official source; an empty result is never a clearance. Sanctions compliance needs human review and a qualified determination. This server feeds that process and does not perform it.

Tools

ToolDescription
sanctions_screen_nameScreen a person, company, vessel, or aircraft name against every loaded watchlist at once
sanctions_screen_identifierLook up an IMO number, SWIFT/BIC code, wallet address, or passport or national ID number exactly across every loaded watchlist
sanctions_get_designationFetch the full record for one designation by source list and entry ID, published reference number, or (UK and EU) the UN reference number it implements
sanctions_resolve_entityResolve a company name, optionally within a jurisdiction, to ranked GLEIF LEI candidates
sanctions_get_entityFetch the GLEIF Level 1 record for an LEI, with its entity status and successors and a sanctions cross-reference of its names, LEI, and registration number
sanctions_trace_ownershipTrace an LEI's parents and children, optionally cross-referencing every entity in the graph
sanctions_list_sourcesList the loaded sources with record counts, licenses, mirror freshness, and each list's last harvest and document date

Resources

ResourceDescription
sanctions://designation/{source}/{entryId}One sanctions designation by source and entry ID, published reference number, or (UK and EU) UN reference number
sanctions://entity/{lei}One GLEIF Level 1 entity by LEI
sanctions://sourcesLoaded sources with counts, plus each mirror's readiness and as-of timestamp
skill://sanctions-screening-guide/SKILL.mdConsumer guide for identity confirmation, ownership continuation, and screening uncertainty

The three sanctions:// data resources are also reachable through the tools, for clients that don't surface resources. The guide is also published in the plugin, npm package, and bundle under skills/sanctions-screening-guide/.

Prompts

PromptDescription
sanctions_vet_counterpartyRun a counterparty due-diligence pass: screen, resolve, trace ownership, summarize

Capability reference

sanctions_screen_name tool

  • name in any script (at most 64 words and 1,024 characters) plus optional sources, entityType, and minScore filters; matchMode is strict (default) or fuzzy. Strict runs a fuzzy pass over each selected list it finds nothing on, and over the UK and UN lists either way for a name holding a letter outside the Latin script: a full pass when it finds nothing on any list, otherwise one that adds, after the strict hits, only candidates covering every word of the name, by spelling or by sound, other than legal forms, articles and other function words, and the jurisdiction codes uk, usa, uae, and rf. fuzzySources names the lists a fuzzy pass searched; up to 100 hits per page (limit, default 25) with offset
  • Limits above 100 clamp with a notice; SANCTIONS_NORMALIZE_INPUTS=false restores rejection above the maximum
  • Hits carry source, sourceEntryId, the list's published referenceNumber where it has one, unReferenceNumber on a UK or EU hit whose list publishes one, matchedName with its matchedNameType, and matchType (exact / strong / approximate); strong is every word of the name present, a legal form counting in any spelling of the same form (Ltd and Limited, LLC and OOO; never LLC and Ltd)
  • Approximate hits add the raw Jaro-Winkler score (0–1) and queryTokenCoverage: covered counts the words matched by spelling or by sound, and phonetic (absent when zero) how many of those matched by sound alone, through an equal primary Double-Metaphone key of three or more characters (gaddafi and qadhafi), neither word a legal form, article or other function word, or jurisdiction code. A sound match never admits a candidate or raises a score, and of two hits with equal score and coverage the one with fewer sound matches ranks first
  • A typed screen includes records whose source omitted the entity type; those hits remain unknown. Published birth dates (with circa where supplied), nationalities, and distinct address countries appear on each hit when available, preserving date precision and ranges for comparison before designation lookup
  • Approximate screening compares native forms and deterministic Russian-alphabet romanizations in both directions, always keeping the name and alias type exactly as published. Derived equality remains approximate; it is neither an official alias nor an identity determination. Native candidates take priority within each list's independent 2,000-name fuzzy pool; romanized forms and first-four-code-point deletion signatures supplement remaining capacity, so typo recall is bounded
  • sources names every selected list a hit's party is on. OFAC publishes a party on the SDN List and a non-SDN list under one entry ID in both of its files; with both OFAC lists selected that party is one hit, counted once, naming both even when the screen matched one record. Its other fields, the designation date included, come from the source record: ofac_sdn, unless the Consolidated record matched alone or better
  • totalAvailable, hasMore, and nextOffset page the rest, and paging reaches every match counted; totalAvailableBasis marks the count exact (no fuzzy pass ran) or a lower_bound (a fuzzy pass ran), and a notice asks for a more distinctive word when a list's fuzzy candidate pool reached its budget

sanctions_screen_identifier tool

  • value (an identifier as you hold it) plus optional type (any default, imo, swift_bic, digital_currency_address, passport, national_id) and sources
  • Exact match after normalization, never fuzzy and never scored: spacing, letter case, and - . / are ignored; an IMO number matches with or without its IMO prefix; a SWIFT/BIC compares on its first eight characters, so a branch BIC11 matches its institution's BIC8; a wallet address folds case only for hex (0x…), bech32 (bc1…, ltc1…, bnb1…), and cashaddr encodings, while base58 addresses compare exactly
  • type matches on each list's published label: imo includes OFAC Vessel Registration Identification, UK IMO Number, and EU IMO (vessel identification); an otherwise unclassified label, including IMO Company Number, also qualifies when its normalized value is IMO followed by seven digits. Established passport, national-ID, SWIFT/BIC, and wallet labels retain their categories. swift_bic is SWIFT/BIC and SWIFT BIC; digital_currency_address is OFAC Digital Currency Address - <code>; passport and national_id cover the lists' passport and national-ID labels. any also reaches every label with no category (MMSI, call signs, tail numbers, tax and registration numbers, email, websites)
  • One hit per designation, ordered by list then entry ID, each with the matchedIdentifiers that matched as published and its sources, an OFAC party on both OFAC lists being one hit naming both; not paged. An identifier a list prints only in free-text remarks, or bundled with other numbers in one field, does not match

sanctions_get_designation tool

  • source (one of the eleven codes above) and entryId: the sourceEntryId from a screening hit, or the reference number the list publishes (UN QDe.004, EU EU.27.28, UK OFSI Group ID 14196) or, on uk and eu, the UN reference number the entry implements (TAe.010). Matched trimmed and case-insensitive: entry ID first, then reference number, then UN reference number, then a UN reference number in another zero padding (LYi.28, LYi.028), each only when the earlier ones match nothing. A reference number or UN reference number two designations share fails as reference_ambiguous, naming both. CSL records retain the provider's opaque id; missing entity type remains unknown
  • Returns referenceNumber beside sourceEntryId where the list publishes one; OFAC publishes none, its entry ID being its published number
  • Returns unReferenceNumber for a UK or EU designation whose list publishes one, as published and never corrected: it can differ from the UN list's own in case or padding (a lookup ignores both), name no current UN listing, or be carried by two designations. It is a link to check against the un record, not proof of identity
  • The EU list publishes no primary name, so primaryName is its first Latin-script alias carrying a function; with none, when the first alias is in another script, the first Latin-script EN alias, then the first untagged Latin-script alias, then the first Latin-script alias. Every other published name follows as an alias in document order
  • All published aliases, including the UK list's non-Latin-script names (typed aka) and the UN list's original-script names (typed primary), identifiers, addresses, dates and places of birth, nationalities, descriptive features, program, legal basis, and designation date; a field the source omitted is absent, never filled in
  • Identifiers cover identity documents plus the SWIFT/BIC codes, digital-currency addresses, vessel call signs, aircraft tail and serial numbers, phone numbers, email addresses, and websites a list publishes, each typed with the list's own label and its value verbatim
  • Dates of birth are ISO 8601 at the precision the source published (1952-10-07, 1946-08, 1938, or an interval such as 1955/1957), with circa: true where the source marks one approximate; designationDate normalizes valid complete dates to YYYY-MM-DD, retaining unparseable published text. CSL uses its published start_date, without substituting dates from remarks
  • An OFAC party is dated from its entries on the lists its file publishes: the SDN List for ofac_sdn, the non-SDN lists for ofac_consolidated, earliest first. A party on both files can carry a different date on each
  • legalBasis is the instrument the list cites, verbatim: OFAC's legal-basis references (Executive Order 14024 (Russia)), the EU regulation title (2024/1488 (OJ L27052024)), or the UK regime's regulations (The Russia (Sanctions) (EU Exit) Regulations 2019), several joined with ; . The UN list publishes none
  • features carries what a list publishes to describe the party rather than identify it, each typed with the list's own label, in published order: OFAC's vessel flag, type, owner, and tonnage, aircraft model, operator, and manufacture date, title, gender, and sanctions notes (Secondary sanctions risk: See Section 11 of Executive Order 14024.), and the UK list's designation source and measures imposed (DesignationSource, SanctionsImposed, one feature per |-separated part), then its ship details (CurrentBelievedFlagOfShip, TypeOfShip, YearBuilt, …). A date is ISO 8601 at published precision, with circa: true where OFAC marks it approximate. The EU and UN lists contribute none, and no screening tool matches a feature value. CSL features also retain published restrictions, order flags, end dates, country, notices, and provenance URLs without legal interpretation.

sanctions_resolve_entity tool

  • name in any script (same bound as sanctions_screen_name) plus optional jurisdiction, status, and minScore; matchMode is strict (default), which falls back to a fuzzy pass only when strict finds nothing, or fuzzy; up to 50 candidates per page (limit, default 10) with offset
  • Limits above 50 clamp with a notice; SANCTIONS_NORMALIZE_INPUTS=false restores rejection above the maximum
  • jurisdiction is a country code, which matches the country and every subdivision under it (US matches US-DE and US-CA), or an ISO 3166-2 subdivision code (US-DE), matched exactly; case-insensitive
  • status: issued (default) matches ISSUED, lapsed matches exactly LAPSED, and any applies no filter — the only way to reach RETIRED, DUPLICATE, ANNULLED, PENDING_TRANSFER, PENDING_ARCHIVAL, or MERGED records, each candidate's status naming its state
  • When a status filter excludes every strict match, a notice counts distinct excluded LEIs by registration status and points to status: "any". It retains the jurisdiction filter, marks capped counts as lower bounds, and leaves fuzzy fallback and ranking unchanged
  • Searches every name GLEIF publishes: the legal name, previous legal names, trading names, alternative-language legal names, and ASCII transliterations of a legal name in another script
  • Candidates carry lei, legalName, the matchedName and its matchedNameType (LEGAL_NAME, PREVIOUS_LEGAL_NAME, TRADING_OR_OPERATING_NAME, …, or UNKNOWN for a name stored without a type), and matchType, with score and queryTokenCoverage on approximate matches; one candidate per LEI, paged by the same totalAvailable / totalAvailableBasis / hasMore / nextOffset fields

sanctions_get_entity tool

  • One 20-character lei; returns the legal name, otherNames, legal and headquarters addresses, status, jurisdiction, registration authority, and lastUpdate
  • entityStatus is GLEIF's EntityStatus as published (ACTIVE, INACTIVE, NULL), the legal entity's own state where status is the LEI's. successors lists every successor entity GLEIF names, each by lei, name, or both: a retired, merged, or duplicate LEI can name the entities that took it over. Successors are listed, never screened or followed; pass a successor's LEI to sanctions_get_entity or sanctions_trace_ownership. entityStatusLoaded is false for a record stored before status and successors were read, which says nothing about whether it has either; a GLEIF refresh that updates the record, or mirror:init, loads them
  • Mixed-case LEIs normalize to uppercase for this tool, ownership tracing, and the entity resource, including cursor binding. SANCTIONS_NORMALIZE_INPUTS=false restores uppercase-only validation. Check digits are checked after a lookup miss, so held records remain accessible
  • alternateNames lists every other and transliterated name with its GLEIF type; a name the mirror stored before types were kept reads as UNKNOWN
  • sanctionsHits cross-references the entity against every watchlist: the legal name and every alternateNames entry screened strict (exact, then all tokens present with a legal form matching any spelling of the same form, never fuzzy), and the LEI and registrationAuthorityEntityId looked up exactly as non-document identifiers (never passports, national IDs, IMO numbers, SWIFT/BIC codes, or wallets). The registration number matches only an identifier published for the country of the entity's jurisdiction, and is skipped when the entity publishes no jurisdiction or a not-available placeholder (N/A, n.a.) in place of a number
  • One hit per designation, an OFAC party on both OFAC lists being one hit whose sources names both, exact name and identifier matches first, then strong name matches, capped at 25 after the merge. matchedOn lists every input that produced a hit (legal_name, other_name with its GLEIF type, lei, registration_number); an identifier match adds matchedIdentifiers as the list publishes them, and a hit no name produced carries no matchedName or matchType. No hit carries a score: only an approximate (fuzzy) match has one, and every screen here is strict
  • screeningStatus (screened / not_ready) says whether the cross-reference ran; sanctionsScreen counts distinct designations across every input (totalAvailable), flags a capped list (hasMore), and lists in screenedInputs what was screened beyond the always-screened legal name and LEI

sanctions_trace_ownership tool

  • Root lei, direction (parents / children / both, default both), and depth 1–5 (default 3); screenNodes: true cross-references every node as sanctions_get_entity does (its names strict, its LEI and country-matched registration number as identifiers), up to 10 merged hits per node; a node with no Level 1 record has no name to screen and is looked up by its LEI alone. both is a parents walk plus a children walk from the root, each to depth; it never reaches siblings or co-parents
  • limit defaults to 50 and clamps above 100 records across nodes, then edges, then boundaries; every page but the last holds exactly limit records. Drain nextCursor while hasMore is true; totalAvailable counts those segment records exactly. Edges reference nodes in the assembled segment across pages. Only returned nodes are hydrated and screened. Page size follows the record count alone, so lower limit for smaller pages: a screened node at its ten-hit cap is the largest record
  • Cursors bind the effective query and topology fingerprint; invalid or stale cursors, and a cursor carrying a key the server did not write, require restarting the segment. Entity and screening values remain current between pages, without an immutable snapshot
  • role and depth retain segment placement; ultimate-parent shortcuts are unwalked leaves flagged reachedVia: "ultimate". After draining a segment, re-root each boundary with its supplied direction and depth; deduplicate queued (lei, direction) roots and edge identities because segments overlap. Depth restarts per segment; a missing Level 1 root is accepted only if Level 2 references it
  • truncationReasons distinguishes remaining pages, depth limits, and ultimate leaves. complete requires no remaining page or omitted branch and no missing Level 1 record anywhere in the segment (missingEntityCount); missingEntityLeis is page-local. This covers loaded accounting-consolidation relationships only, never beneficial ownership
  • Each node whose parents the walk read carries parentStatus.direct / .ultimate: relationship, exception (a GLEIF reporting exception, with every reason, such as NATURAL_PERSONS), none, or unknown. unknown means exception data is not loaded, which reportingExceptionsLoaded: false states.
  • screeningStatus (screened / not_requested / not_ready), screenedNodeCount, and flaggedNodeCount; each screened node carries its own sanctionsScreen (hasMore, screenedInputs) and hits with matchedOn and matchedIdentifiers, in the sanctions_get_entity shape

sanctions_list_sources tool

  • No input; one row per sanctions list plus gleif, each with recordCount, url (the configured source URL), and license; the gleif row's recordCount is Level 1 entities and its relationshipCount Level 2 ownership relationships
  • sanctionsReady / sanctionsAsOf and leiReady / leiAsOf report whether each mirror has synced and when; sanctionsAsOf is the last successful local sync in which every sanctions list refreshed, never upstream publication freshness. Not gated on readiness, so it reports an empty mirror instead of failing
  • Each sanctions row carries lastHarvestedAt, when this server last harvested the list successfully, and publishedAt, the date the publisher put on that document at the precision and offset published (OFAC DateOfIssue, EU generationDate, UK DateGenerated, UN dateGenerated, each CSL list's source_last_updated). publishedAt dates the document, not the last change to the list: the UN file is regenerated daily. Both are absent until this server records a harvest of the list, which means unknown, not stale; publishedAt is also absent when the document carried no date this server reads. GLEIF rows carry neither
  • lastRefresh appears only while a sanctions refresh is running (in_progress, which a killed refresh also reads as) or after one failed (error, with failedSources naming the lists that failed: empty when none failed and the run stopped for another reason, absent when which failed is unknown). A list that failed keeps its earlier lastHarvestedAt and publishedAt
  • reportingExceptionsLoaded, and on the gleif row a reportingExceptionCount once the reporting exceptions are loaded
  • alternateNamesIndexed: whether GLEIF's trading, previous, alternative-language, and transliterated names are indexed; until mirror:init builds the index, sanctions_resolve_entity searches legal names only
  • entityStatusLoaded: whether a completed mirror:init golden-copy load has written entity status and successors for every entity in that copy; a sanctions_get_entity record's own entityStatusLoaded is the per-record answer

sanctions://designation/{source}/{entryId} resource

  • source is one of the eleven list codes, entryId the list's own ID, its published reference number, or (UK and EU) the UN reference number the designation implements, resolved as sanctions_get_designation resolves it and decoded once when percent-encoded; returns the sanctions_get_designation payload as application/json
  • Cached for an hour, scoped private

sanctions://entity/{lei} resource

  • The sanctions_get_entity Level 1 payload for one lei, without the sanctions cross-reference, which is tool-only
  • Cached for an hour, scoped private

sanctions://sources resource

  • The sanctions_list_sources payload, unchanged
  • ttlMs: 0: never cached, because readiness and the as-of timestamps are the payload

sanctions_vet_counterparty prompt

  • Arguments: name required; jurisdiction optional (a country code, which includes its subdivisions, or an ISO 3166-2 subdivision code)
  • Returns one user message that screens the name (and any identifier the caller holds, with sanctions_screen_identifier), resolves it to an LEI (treating a retired, merged, or duplicate LEI's successor as the entity to vet), traces ownership with screenNodes: true, pulls each hit's designation record, and asks for a summary that treats every match as a candidate to verify and says, from matchedOn, which of the entity's names or identifiers produced it. It names GLEIF parents as accounting-consolidation parents, not beneficial owners, and reports a reporting exception's reasons rather than reading it as "no parent"

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

Sanctions-screening-specific:

  • One screen covers the eleven sanctions and export-control lists above; the matching list shows up as per-hit provenance
  • Offline and keyless, with no per-request upstream rate limit: all lists are normalized into local SQLite + FTS5 mirrors via the framework MirrorService
  • Per-alias name index, so a query matches any of an entity's names in one FTS scan, and a per-identifier index for exact lookup by IMO number, SWIFT/BIC, wallet address, or document number
  • Strict-then-fuzzy matching: exact-normalized, then all tokens present (FTS5, a legal form matching any spelling of the same form), then Jaro-Winkler + Double-Metaphone over a 2,000-candidate pool per list, so adding a list never pushes another list's candidates out, with every admitted candidate reachable by paging
  • GLEIF Level 1 (who is who) and Level 2 (who owns whom) for entity resolution and ownership tracing

Agent-friendly output:

  • Real signal with provenance: approximate hits carry the raw Jaro-Winkler score and a literal queryTokenCoverage count, never a blended confidence; every hit names its list, program, designation date, and the name that matched, typed primary / aka / fka / low-quality-aka
  • Decision-support caveat in the output of sanctions_screen_name, sanctions_screen_identifier, sanctions_get_designation, sanctions_get_entity, and sanctions_trace_ownership
  • Disclosed gaps: totalAvailableBasis, screeningStatus, complete / truncated / missingEntityLeis, and each node's parentStatus say what a response did not cover
  • Typed errors: every data tool and sanctions:// resource except the sources listing fails as mirror_not_ready (retryable) until its mirror is loaded; unknown IDs fail as designation_not_found or lei_not_found, an LEI the mirror lacks whose ISO 17442 check digits fail as invalid_lei_checksum (a mistyped character), and a reference number or UN reference number two designations share as reference_ambiguous; a name with no letter or digit fails as name_not_searchable, one past the length bound as name_too_long, and an identifier with nothing left once spacing and separators are removed as identifier_not_searchable

Getting started

Public Hosted Instance

A public instance is available at https://sanctions-screening.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

json
{  "mcpServers": {    "sanctions-screening-mcp-server": {      "type": "streamable-http",      "url": "https://sanctions-screening.caseyjhand.com/mcp"    }  }}

Self-Hosted / Local

Add the following to your MCP client configuration file. The mirror is not bundled, and the npm package cannot build it: run bun run mirror:init from a clone (Installation) or inside the Docker image, then point SANCTIONS_MIRROR_PATH at the result (see Mirror lifecycle).

json
{  "mcpServers": {    "sanctions-screening-mcp-server": {      "type": "stdio",      "command": "bunx",      "args": ["@cyanheads/sanctions-screening-mcp-server@latest"],      "env": {        "MCP_TRANSPORT_TYPE": "stdio",        "MCP_LOG_LEVEL": "info"      }    }  }}

Or with npx (no Bun required):

json
{  "mcpServers": {    "sanctions-screening-mcp-server": {      "type": "stdio",      "command": "npx",      "args": ["-y", "@cyanheads/sanctions-screening-mcp-server@latest"],      "env": {        "MCP_TRANSPORT_TYPE": "stdio",        "MCP_LOG_LEVEL": "info"      }    }  }}

For Streamable HTTP, set the transport and start the server:

sh
MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http# Server listens at http://localhost:3010/mcp

Prerequisites

  • Bun v1.4.4 or higher (or Node.js v24+).
  • Disk for the local mirror; GLEIF Level 1 takes most of it. No source needs an API key.

Installation

  1. Clone the repository:
sh
git clone https://github.com/cyanheads/sanctions-screening-mcp-server.git
  1. Navigate into the directory:
sh
cd sanctions-screening-mcp-server
  1. Install dependencies:
sh
bun install
  1. Configure environment:
sh
cp .env.example .env# edit .env if you need to override defaults (all optional)
  1. Populate the mirror:
sh
bun run mirror:init

Configuration

Every source is keyless, so nothing here is required.

VariableDescriptionDefault
SANCTIONS_MIRROR_PATHFilesystem path for the SQLite mirror; use a persistent volume when hosted../data/sanctions.db
SANCTIONS_REFRESH_CRONCron for the scheduled refresh (HTTP transport only). A supervised child refreshes the sanctions lists and their indexes, then applies GLEIF deltas under one fresh 4-hour bound. A gap that needs mirror:init is logged; the schedule never loads golden copies.0 4 * * *
SANCTIONS_REFRESH_SKIP_GLEIFSet to 1 to skip the GLEIF leg of the scheduled refresh and of mirror:refresh.unset
SANCTIONS_FUZZY_MIN_SCOREJaro-Winkler floor for fuzzy matches when minScore is omitted.0.85
SANCTIONS_NORMALIZE_INPUTSUppercase mixed-case LEIs and clamp name-screen and entity-resolution limits, with logs and counters for each operation. Set to false to restore uppercase-only schemas and rejection above the limit maxima. Read at startup, including from .env.true
OFAC_SDN_URLOFAC SDN advanced-XML URL.official OFAC URL
OFAC_CONSOLIDATED_URLOFAC Consolidated advanced-XML URL.official OFAC URL
EU_FSF_URLEU consolidated XML URL. Its token query value is a static public path component, not a credential.official EU URL
UK_SANCTIONS_URLUK Sanctions List (UKSL) XML URL.official FCDO URL
UN_SC_URLUN Security Council consolidated XML URL.official UN URL
CSL_URLMirror-download override for the shared BIS/State CSL bulk JSON; no search API key.https://data.trade.gov/downloadable_consolidated_screening_list/v1/consolidated.json
GLEIF_GOLDEN_COPY_BASE_URLGLEIF golden-copy and delta download API.https://goldencopy.gleif.org
MCP_TRANSPORT_TYPETransport: stdio or http.stdio
MCP_HTTP_PORTHTTP server port.3010
MCP_SESSION_MODEHTTP session mode: stateless, stateful, or auto. createApp() declares stateless; setting the variable overrides it.stateless
MCP_LOG_LEVELLog level (debug, info, warning, error, etc.).info
LOG_TOOL_FAILURE_PAYLOADSLog each failed tool call's arguments and result, redacted by key name and capped at LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES (default 16384). A secret inside a free-form value is not redacted.false

See .env.example for the full list of optional overrides.

Running the server

Local development

  • Build and run:

    sh
    # One-time buildbun run rebuild
    # Run the built serverbun run start:stdio# orbun run start:http
  • Run checks and tests:

    sh
    bun run devcheck   # Lint, format, typecheck, security, changelog syncbun run test       # Vitest test suitebun run lint:mcp   # Validate MCP definitions against spec

Mirror lifecycle

Upgrading from 0.5.1 or earlier: run bun run mirror:refresh to load the six BIS/State CSL lists; optionally set SANCTIONS_REFRESH_SKIP_GLEIF=1. Existing readiness does not prove those lists are populated. sanctions_list_sources reports configured lists and stored counts, with refresh guidance for zero-row CSL sources.

The mirror loads out-of-band, never on the request path: bun run mirror:init does the full load once, bun run mirror:refresh keeps it current (HTTP deployments also refresh on SANCTIONS_REFRESH_CRON), and bun run mirror:verify reports readiness and counts. When upgrading from an earlier release, run mirror:refresh once (from 0.3.0 or earlier, mirror:init). Failure handling, upgrade and rollback behavior, and disk sizing are in docs/mirror.md.

Docker

sh
docker build -t sanctions-screening-mcp-server .docker run --rm -p 3010:3010 -v sanctions-data:/usr/src/app/data sanctions-screening-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/sanctions-screening-mcp-server. Mount a volume at /usr/src/app/data so the mirror survives restarts, and populate it with bun run mirror:init via docker exec. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

DirectoryPurpose
src/index.tscreateApp() entry point: registers the surface, inits the screening service, schedules the HTTP refresh.
src/configServer-specific environment variable parsing and validation with Zod.
src/mcp-server/toolsTool definitions (*.tool.ts) and the shared screening caveat.
src/mcp-server/resourcesResource definitions (*.resource.ts).
src/mcp-server/promptsPrompt definitions (*.prompt.ts).
src/services/screeningScreening service: mirrors, normalized schema, OFAC/EU/UK/UN/CSL/GLEIF ingesters, matching engine.
skills/sanctions-screening-guide/Consumer workflow guide, published through MCP, plugins, npm, and the bundle.
scripts/mirror-*.tsMirror lifecycle CLI: init, refresh, verify, seed.
tests/Tool, resource, prompt, service, integration, fuzz, and smoke tests.

Development guide

See CLAUDE.md/AGENTS.md for development guidelines and architectural rules. The short version:

  • Handlers throw, framework catches — no try/catch in tool logic
  • Use ctx.log for request-scoped logging; the mirror is reached through getScreeningService(), not ctx.state
  • Register new tools and resources via the barrels in src/mcp-server/*/definitions/index.ts
  • Wrap external sources: validate raw → normalize to the common schema → return the output schema; never fabricate fields a source omits, and never synthesize a confidence score

Attribution

This server redistributes open data from these sources, cited per their terms:

SourcePublisherLicense
OFAC SDN and Consolidated listsUS Department of the Treasury, Office of Foreign Assets ControlUS Government public domain
BIS Entity, Denied Persons, Unverified, Military End User; State ITAR Debarred and Nonproliferation SanctionsUS Departments of Commerce and State, via ITA CSLUS Government public domain; ITA terms
EU Consolidated Financial Sanctions ListEuropean Commission / EEASFreely redistributable
UK Sanctions List (UKSL)UK Foreign, Commonwealth & Development OfficeOpen Government Licence v3.0 (attribution required)
UN Security Council Consolidated ListUnited Nations Security CouncilFreely redistributable
GLEIF LEI data (Level 1 + Level 2)Global Legal Entity Identifier FoundationCC0 1.0 Universal

UKSL has been the single authoritative UK source since the OFSI Consolidated List closed on 28 January 2026.

This product uses the International Trade Administration’s Data API but is not endorsed or certified by the International Trade Administration.

Verify CSL candidates and their published restrictions against the official agency lists and Federal Register publications. A published end date or order flag is retained as source data, never interpreted as clearance or a legal-status determination. Mirror timestamps report successful local synchronization. A list's publishedAt is the publisher's date on the document harvested, not proof of when the list's content last changed.

Contributing

Issues are welcome. Run checks and tests before submitting:

sh
bun run devcheckbun run test

License

Apache-2.0 — see LICENSE for details.

Source: README.md at commit b21a6ff

Tools

7

sanctions_screen_name

sanctions-screening-mcp-server: screen name

Screen a name (person, company, vessel, aircraft) against loaded sanctions and export-control watchlists — OFAC SDN + Consolidated, EU, UK, UN, and the six BIS/State CSL lists — alias- and fuzzy-aware. Check sanctions_list_sources for coverage before interpreting an empty result; zero-record CSL lists are not loaded. Returns scored potential matches with the source list, sanctioning program, designation date, and the matched alias; an OFAC party both OFAC lists publish under one entry ID is one hit, its sources naming both lists. Strict mode (default) matches exact-normalized then all-tokens-present, a legal form matching any spelling of the same form (Ltd and Limited, LLC and OOO), then runs a fuzzy pass over each selected list strict finds nothing on, and over the UK and UN lists either way for a name holding a letter outside the Latin script: a full pass when strict finds nothing on any list, otherwise one that adds only candidates covering every word of the name other than legal forms, articles and other function words, and the jurisdiction codes uk, usa, uae, and rf, by spelling or by sound, ranked after the strict hits. Fuzzy mode runs the fuzzy pass over every selected list. It adds Jaro-Winkler and phonetic matching and labels hits approximate with a raw 0–1 similarity score plus the count of query tokens the candidate covers, which orders candidates that tie on score; fuzzySources names the lists it searched. Results are paged: totalAvailable and hasMore report matches beyond the returned page, and nextOffset retrieves them. This is a screening AID for a human/compliance review, NOT a compliance determination: a hit means "review this candidate against the official source," and an empty result never means "cleared."

ParametersnamerequiredlimitoffsetsourcesminScorematchModeentityType

sanctions_screen_identifier

sanctions-screening-mcp-server: screen identifier

Look up an identifier — a vessel or company IMO number, a SWIFT/BIC code, a digital-currency wallet address, a passport or national ID number, or any other identifier a list publishes — against loaded sanctions and export-control watchlists — OFAC SDN + Consolidated, EU, UK, UN, and the six BIS/State CSL lists. Check sanctions_list_sources for coverage. Exact match after normalization, with no fuzzy or partial matching and no score: spacing, letter case, and the separators - . / are ignored, an IMO number matches with or without its IMO prefix, a SWIFT/BIC code compares on its first eight characters so a branch code matches its institution, and a wallet address folds case only where its encoding is case-insensitive (hex, bech32, cashaddr — never base58). Returns every designation that publishes a matching identifier, one per designation — an OFAC party both OFAC lists publish under one entry ID is one hit, its sources naming both lists — with the identifiers that matched as published; sanctions_get_designation pulls the full record. This is a screening AID for a human/compliance review, NOT a compliance determination: a hit means "review this candidate against the official source," and an empty result never means "cleared" — an identifier a list prints only in free-text remarks, or bundled with other numbers in one field, does not match.

Parameterstypevaluerequiredsources

sanctions_get_designation

sanctions-screening-mcp-server: get designation

Fetch the full record for one sanctions designation by source list + entry ID, the list's published reference number, or, for a UK or EU designation, the UN reference number it implements — the drill-in after sanctions_screen_name or sanctions_screen_identifier surfaces a candidate, or the lookup for a reference a notice cites (UN QDe.004, EU EU.27.28, UK OFSI Group ID, or UN TAe.010 on the UK list). Returns all published aliases, identifiers (passport, national ID, tax and registration numbers, SWIFT/BIC codes, digital-currency addresses, vessel call signs, aircraft tail and serial numbers, phone numbers, email addresses, websites), addresses, dates and places of birth at the precision the source published, nationalities, descriptive features (a vessel's flag, type, and tonnage; an aircraft's model and operator; a title or gender; sanctions notes; the UK measures imposed and designation source), sanctioning program, legal basis, designation date, and the UN reference number a UK or EU designation implements. The record reflects exactly what the source published; missing fields mean the source omitted them. This is a screening aid — the designation record supports a compliance review, it is not itself a determination.

ParameterssourcerequiredentryIdrequired

sanctions_list_sources

sanctions-screening-mcp-server: list sources

List supported watchlists (OFAC SDN + Consolidated, EU, UK, UN, BIS Entity/Denied Persons/Unverified/Military End User, State ITAR Debarred/Nonproliferation) and GLEIF datasets with current mirrored counts, source URLs, licenses, readiness, and as-of timestamps. Each sanctions list carries lastHarvestedAt, its last successful harvest, and publishedAt, the date its publisher put on that document (not when the list's content last changed); both are absent until this server records a harvest of the list. lastRefresh reports a sanctions refresh that is running or failed and names the lists that failed; sanctionsAsOf is the last refresh in which every list harvested. coverageNotice names unloaded CSL lists and how to refresh them; prior mirror readiness does not establish coverage of newly added lists. For GLEIF, reports Level 2 ownership relationships, reporting-exception coverage, alternate-name index readiness, and whether entity status and successors are loaded. Use this for provenance, freshness, and coverage on any result. Attribution: UK data is under the Open Government Licence v3.0; BIS and State CSL data is supplied by the International Trade Administration under its published terms. This product uses the International Trade Administration’s Data API but is not endorsed or certified by the International Trade Administration.

Takes no parameters.

sanctions_resolve_entity

sanctions-screening-mcp-server: resolve entity

Resolve a company or organization name (with an optional jurisdiction: a country code, which includes its subdivisions, or an ISO 3166-2 subdivision code) to candidate GLEIF Legal Entity Identifiers (LEIs), ranked. This turns a free-text counterparty name into a stable global identifier that sanctions_get_entity and sanctions_trace_ownership key off. Every name GLEIF publishes takes part: the legal name, previous legal names, trading names, alternative-language legal names, and ASCII transliterations of a legal name in another script — each candidate reports the name it matched on and that name's type, one candidate per LEI. Strict mode (default) matches exact-normalized then all-tokens-present; fuzzy mode (or auto when strict is empty) adds Jaro-Winkler scoring labeled approximate with a raw 0–1 score plus the count of query tokens the matched name covers, which orders candidates that tie on score. Results are paged: totalAvailable and hasMore report candidates beyond the returned page, and nextOffset retrieves them. Returns potential matches to confirm against the GLEIF record — name resolution is a candidate ranking, not an authoritative identification.

ParametersnamerequiredlimitoffsetstatusminScorematchModejurisdiction

sanctions_get_entity

sanctions-screening-mcp-server: get entity

Fetch the full GLEIF Level 1 record for one LEI: legal name, other/trading names, legal and headquarters addresses, registration status, entity status and successor entities, jurisdiction, registration authority and ID, and last-update date — plus a sanctions cross-reference against all loaded watchlists. The cross-reference screens the legal name and every other and transliterated name strict (exact, then all tokens present with a legal form matching any spelling of the same form, such as Ltd and Limited or LLC and OOO — never fuzzy, unlike sanctions_screen_name), and looks up the LEI and the registration number as exact non-document identifiers, the registration number matching only an identifier published for the country of the entity's legal jurisdiction. Hits merge to one per designation, an OFAC party both OFAC lists publish to one hit whose sources names both: matchedOn names every input that produced each, and a hit only an identifier produced carries matchedIdentifiers and no matchedName. The screening cross-reference is a screening AID: a hit is a candidate to verify against the official source, and no hit is not a clearance. screeningStatus says whether that cross-reference actually ran — an empty sanctionsHits under not_ready means the sanctions mirror was unavailable, not that nothing matched. sanctionsScreen says whether the hit list is the whole set: it reports how many potential matches existed before the cap, so a capped cross-reference is distinguishable from a complete one. A retired, merged, or duplicate LEI can name successors, the entities that took it over: pass a successor's LEI to sanctions_get_entity or sanctions_trace_ownership, since successors are listed, never screened or followed; entityStatusLoaded false means the record was stored before entity status and successors were read, not that it has none. LEI must be a 20-character GLEIF identifier (18 alphanumerics + 2 check digits).

Parametersleirequired

sanctions_trace_ownership

sanctions-screening-mcp-server: trace ownership

Trace a paged GLEIF Level 2 ownership segment from a 20-character LEI (use sanctions_resolve_entity to obtain one). Direction both walks parents and children separately from the root, never sideways into siblings or co-parents; parents-side placement wins cycles. Ultimate-parent edges are shortcuts, never walked hops; ultimate-only nodes are flagged reachedVia: ultimate. Drain nextCursor with the same query, then re-root each boundary with its LEI, same-side direction and depth, including at depth five; deduplicate branch roots and edges across segments. Pages emit nodes, then edges, then boundaries: limit records each (50 default, 100 maximum), the last page the remainder. Edges reference nodes across assembled pages. Cursors bind query and topology; changed topology requires restarting without a cursor. Entity and screening values read current mirrors, not an immutable snapshot. Set screenNodes to cross-reference only this page of nodes as sanctions_get_entity does: legal, other and transliterated names strict (exact then all tokens present, a legal form matching any spelling of the same form, never fuzzy), LEI and country-matched registration number as exact non-document identifiers, with merged designation hits and matchedOn inputs. A node missing Level 1 is screened by LEI alone. Every hit is a candidate to verify; no hit is a clearance. Each eligible node retains direct and ultimate parentStatus: relationship, reporting exception and its reasons, none, or unknown when exceptions are not loaded. Read hasMore and truncationReasons separately from segment-wide missingEntityCount and page-local missingEntityLeis, screening counts and per-node ten-hit cap disclosures. A screening aid, not a compliance determination; a finished segment never proves full beneficial ownership.

ParametersleirequireddepthlimitcursordirectionscreenNodes

Version history

10
  1. v0.7.0LatestNov 19, 2026
  2. v0.6.1Nov 11, 2026
  3. v0.6.0Nov 1, 2026
  4. v0.5.1Oct 20, 2026
  5. v0.5.0Oct 4, 2026
  6. v0.4.0Sep 25, 2026
  7. v0.3.0Sep 25, 2026
  8. v0.2.0Sep 25, 2026
  9. v0.1.12Sep 21, 2026
  10. v0.1.11Sep 16, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts