pseudonym-mcp

Local pseudonymisation tools for LLM workflows — replace detected PII with opaque tokens before you hand text to a cloud LLM, then restore those tokens afterward.

Expose MCP tools (mask_text and unmask_text) that your client or agent can call as an explicit privacy step. The server detects PII locally, replaces it with opaque tokens, and keeps the token mapping in memory for later restoration.

It is a defense-in-depth measure, not a compliance silver bullet. Read the Limitations and GDPR & AI Compliance sections before assuming this stack does more than it does.

What you get

• 46 recognizers across twelve locales, all of them live by default: Poland (PESEL, NIP, REGON, dowód, paszport, księga wieczysta), the EU (IBAN with mod-97, VAT for all 27 member states, plus DE, IT, ES, FR, NL, CZ/SK, SE, FI and UK national IDs) and the US (SSN, ITIN, EIN, ABA routing, cards). 24 of them verify a real check digit. --lang narrows that set when you want fewer false positives — see Locale coverage is fail-closed. Heuristic language detection (detectLanguage()) infers the language from text content — --lang remains the authoritative override.
• Hybrid NER engine: Regex for structured PII (SSN, credit cards, IBAN, email, phone) + local Ollama LLM for unstructured entities (names, organisations).
• Local-detection architecture: Detection and substitution happen on your machine when the MCP tool is called. The cloud LLM call still happens (that's the point) — but it can see tokens instead of detected PII when your workflow uses the masked output.
• Session-keyed mapping store: Tokens like [PERSON:1] map back to originals in an isolated, per-request session. Multiple round-trips preserve token coherence.
• Unmask workflow support: mask_text returns auto_unmask for clients that want to honor that preference, but this server does not intercept arbitrary LLM responses automatically.
• Flexible engines: Run regex only (no Ollama required), llm only, or hybrid (default).
• Strict validation: SSN area-number validation, credit card Luhn checksum, PESEL checksum — all configurable.
• Graceful degradation: If Ollama is unavailable, the regex phase still runs and no exception is thrown.
• MCP-native: Works with Claude Code, Claude Desktop, Cursor — any MCP-compatible client.

❌ Without / ✅ With

❌ Without pseudonym-mcp:

• Prompt: "John Smith, SSN 123-45-6789, card 4111 1111 1111 1111" → sent verbatim to the LLM provider
• Every name, ID number, and credit card in your prompt is processed and potentially logged by the provider
• A breach at the provider's end exposes those values in cleartext
• Sending personal data to a non-EU LLM provider without further safeguards raises GDPR Article 44 questions you'll need to answer

✅ With pseudonym-mcp used before the cloud call:

• The same prompt can become "[PERSON:1], SSN [SSN:1], card [CREDIT_CARD:1]" when you call mask_text first
• The LLM reasons about structure and content without seeing those detected values in cleartext
• The response can be locally de-tokenised with unmask_text before reaching the user
• Detected direct identifiers are no longer shipped upstream — though structure, dates, indirect references, and any missed PII still are

This is a meaningful reduction in cleartext PII exposure. It is not "no personal data leaves your machine" — see Limitations.

GDPR & AI Compliance

pseudonym-mcp is relevant to compliance work, but it is a technical control, not a compliance product. Whether you are compliant with any specific regulation depends on your full stack, your role (controller/processor), your contracts, your DPIA, and your jurisdiction.

Why this matters

The EU General Data Protection Regulation (GDPR) classifies names, national ID numbers (like SSN or PESEL), bank account numbers (IBAN), email addresses, credit card numbers, and phone numbers as personal data under Article 4(1). Sending this data to a cloud LLM provider constitutes processing under Article 4(2). Pseudonymisation is explicitly recognised under Art. 4(5) as a risk-reduction measure — but, critically, pseudonymised data is still personal data (Recital 26).

The honest bottom line: pseudonymisation under GDPR Art. 4(5) is not anonymisation. The data remains personal data in your system, and Art. 44 transfer obligations are not switched off just because you tokenised the name field.

AI Act alignment

The EU AI Act places additional requirements on high-risk AI systems that process personal data. Using pseudonym-mcp as an intermediary layer can:

• Support data minimisation in your AI system's data flows.
• Help document a technical control for transparency and human-oversight requirements.
• Align with the principle of technical robustness and safety (Art. 15) by limiting cleartext PII exposure.

It does not change your AI Act risk classification on its own — classification is a function of use-case and deployment context, not of the masking step in front of the model.

US & international applicability

The tool is also relevant outside the EU, with the same caveats:

• CCPA / CPRA (California) — reduces personal information sent to third-party processors; doesn't change controller/business obligations or consumer rights.
• HIPAA (US healthcare) — pseudonymised PHI is still PHI under HIPAA. Using this tool does not eliminate the need for a BAA with your cloud LLM provider if you're a covered entity or business associate. It can be part of a defensible safeguard posture; it cannot substitute for one.
• PCI DSS (payment industry) — Luhn-validated detection reduces the chance card numbers ride in cleartext to an LLM. It is one control; PCI scope, segmentation, and storage rules are separate concerns.
• SOC 2 — useful evidence of a technical control limiting PII exposure. Auditors will look at the full picture, not just this layer.
• PIPEDA (Canada), LGPD (Brazil), POPIA (South Africa) — all require appropriate safeguards for cross-border personal data transfers. This tool is a relevant safeguard, not a substitute for the legal basis of the transfer.

Sector-specific applicability

In every row of this table, pseudonym-mcp is a useful building block. None of those regimes can be satisfied by a masking tool alone.

How it works

Your App / Claude Desktop
        │
        │  explicit mask_text tool call with PII
        ▼
┌─────────────────────────┐
│      pseudonym-mcp      │
│                         │
│  Phase 1: Pattern NER   │  ← 46 rules: national IDs, tax numbers,
│                         │    IBAN, VAT, cards, wallets, devices
│                         │    scored, checksum-verified, context-aware
│  Phase 2: Ollama NER    │  ← PERSON, ORG  (local LLM)
│  MappingStore (session) │  ← [TAG:N] ↔ original value
└────────────┬────────────┘
             │  masked text returned to the client/agent
             ▼
      Your workflow sends the masked text
             ▼
      Cloud LLM API
      (Claude / GPT-4 / Gemini)
             │
             │  response with [TAG:N] tokens
             ▼
┌─────────────────────────┐
│      pseudonym-mcp      │
│   unmask_text / revert  │  ← tokens → originals
└────────────┬────────────┘
             │  restored response
             ▼
        Your App / User

Token format

US / English identifiers (en pack):
[PERSON:1]       John Smith
[SSN:1]          123-45-6789
[CREDIT_CARD:1]  4111 1111 1111 1111
[ORG:1]          Acme Corp
[EMAIL:1]        john@acme.com
[PHONE:1]        (555) 123-4567

Polish identifiers (pl pack):
[PERSON:1]       Jan Kowalski
[PESEL:1]        90010112318
[ORG:1]          Auto-Lux
[NIP:1]          526-000-00-05
[REGON:1]        123456785
[IBAN:1]         PL27114020040000300201355387
[EMAIL:1]        jan@example.pl
[PHONE:1]        +48 123 456 789

The mapping is stored in a session-scoped in-memory store. Each mask_text call returns a session_id; pass it back to unmask_text to restore originals.

Real-world example

Meeting note in Claude Code / Obsidian

You have a note:

Meeting with Jan Kowalski (PESEL: 90010112318) from Acme sp. z o.o.
We discussed a contract for 45 000 zł. Contact: jan.kowalski@acme.pl

In Claude Code you type:

Use mask_text on this note, then summarise the key points of the meeting.

First, call mask_text; pseudonym-mcp replaces detected PII locally:

Meeting with [PERSON:1] ([PESEL:1]) from [ORG:1].
We discussed a contract for 45 000 zł. Contact: [EMAIL:1]

Then ask Claude to work from the masked text. Claude responds with tokens:

Meeting with [PERSON:1] from [ORG:1] covered a contract
for 45 000 zł. Follow up via [EMAIL:1].

pseudonym-mcp restores originals locally:

Meeting with Jan Kowalski from Acme sp. z o.o. covered
a contract for 45 000 zł. Follow up via jan.kowalski@acme.pl

If the masked text is what you send upstream, the cloud provider sees the structure of the meeting and the amount — but not the detected name, PESEL, organisation, or email in cleartext. The swap happens on your machine.

Obsidian vault with session_id

# mask the entire vault once — save the session_id
Use mask_text on my notes — remember the session_id

# ask Claude anything across multiple prompts
Summarise all meetings from Q1

# Claude replies with tokens; restore originals
Use unmask_text with session_id abc123 on the response

The session_id keeps the token map alive for the session — the same [PERSON:1] always refers to the same person across notes. That consistency is what makes cross-note reasoning possible; it is also what makes a masked corpus potentially re-identifiable to anyone with side knowledge of your work. Use long-lived sessions deliberately.

MCP Prompt Templates

pseudonym-mcp ships two built-in prompt templates that describe a mask → task → unmask workflow.

Important: MCP prompt templates are convenience helpers, not a privacy boundary. Inline prompt arguments may be visible to the host client or model before tool masking happens. For strongest privacy, call mask_text directly first, then use the returned masked_text in your LLM prompt.

pseudonymize_task — inline text

/pseudonymize_task text="Meeting with Jan Kowalski (PESEL: 90010112318). Contract: 45 000 zł." task="Extract action items"

Intended workflow:

1. pseudonym-mcp masks detected PII locally → [PERSON:1], [PESEL:1]
2. Claude processes the masked text
3. pseudonym-mcp restores originals in the response

Optional lang argument: en or pl. It only annotates the generated prompt text; the packs the server actually runs come from its own --lang.

privacy_scan_file — file / PDF (macOS only)

Requires macos-vision-mcp — a separate MCP server that uses Apple's Vision framework to extract text from PDFs and images on-device. macOS only.

/privacy_scan_file filePath="/Users/me/contracts/nda.pdf" task="Summarise obligations and deadlines"

Intended workflow:

1. macos-vision-mcp extracts text from the file on-device
2. pseudonym-mcp masks detected PII locally
3. Claude processes the masked content
4. pseudonym-mcp restores originals before the response is shown

Optional arguments: task (default: summarise the key points), lang (en or pl — annotates the prompt text only).

Quick Start

Step 1 — Add to your MCP client (example for Claude Code — no install needed):

claude mcp add pseudonym-mcp -- npx -y pseudonym-mcp --engines hybrid

Step 2 — (Optional) Pull an Ollama model for full hybrid NER:

ollama pull llama3

Skip this step if you only need regex-based masking (--engines regex). Without Ollama, you'll catch structured identifiers (SSN, IBAN, cards, email, phone, PESEL) but not free-form names and organisations.

Global install — if you prefer npm install -g pseudonym-mcp, replace npx -y pseudonym-mcp with pseudonym-mcp in all snippets below.

Restart your client. The mask_text and unmask_text tools appear automatically.

Available Tools

mask_text input

{
  "text": "John Smith (SSN: 123-45-6789) works at Acme Corp.",
  "session_id": "optional — omit to create a new session",
  "custom_literals": ["John Smith", "Acme Corp"]
}

mask_text output

{
  "session_id": "3f2a1b...",
  "masked_text": "[PERSON:1] (SSN: [SSN:1]) works at [ORG:1].",
  "auto_unmask": false,
  "ner_status": "ready",
  "active_locales": ["pl", "en", "de", "it", "es", "fr", "nl", "cz", "sk", "se", "fi", "uk"]
}

active_locales lists the packs that ran. If the server was narrowed with --lang, the response also carries disabled_locales and a locale_warning naming the identifiers it cannot see:

{
  "active_locales": ["en"],
  "disabled_locales": ["pl", "de", "it", "es", "fr", "nl", "cz", "sk", "se", "fi", "uk"],
  "locale_warning": "Locale packs disabled: pl (PESEL, NIP, REGON, …); de (Steuer-IdNr, PLZ); … Identifiers from those countries are NOT detected and will pass through unmasked. Start the server without --lang, or with --lang all, to load every pack."
}

unmask_text input

{
  "text": "The case concerns [PERSON:1] at [ORG:1].",
  "session_id": "3f2a1b..."
}

Configuration

mcp-config.json (project root)

{
  "lang": "all",
  "engines": "hybrid",
  "ollamaModel": "llama3",
  "ollamaBaseUrl": "http://localhost:11434",
  "autoUnmask": false,
  "strictValidation": true,
  "sensitivity": "balanced",
  "extraLocales": [],
  "customLiterals": ["Jan Kowalski", "78091512345", "+48 123 456 789"]
}

Locale coverage is fail-closed

Every locale pack runs unless you name one. lang defaults to all, so a fresh server recognises Polish, US, German, Italian, Spanish, French, Dutch, Czech/Slovak, Swedish, Finnish and UK identifiers at once.

This is deliberate. A server narrowed to one pack is indistinguishable from a complete one at the call site: it returns clean-looking text and reports success while every identifier from every other country passes through untouched. A pack that fires on an order number costs an unnecessary token; a pack that stays dormant over a PESEL costs an incident.

Anything that does not name a real pack — a typo, an empty string, all — turns every pack on. Narrowing only ever happens because you asked for it, and when it does the server says so on stderr at startup and in every mask_text response (disabled_locales, locale_warning).

What it costs. Running twelve packs at once means testing twelve national hypotheses against every number, so shapes that are unremarkable in one country get masked in another:

If your documents are single-jurisdiction and those tokens are noise, narrow the server on purpose — --lang en, --lang pl --extra-locales de,it — and accept that identifiers from the packs you dropped will not be detected.

Where the config file is read from

mcp-config.json is looked up in the server's working directory, which for an MCP-spawned process is the client's working directory, not the installed package. The copy shipped inside the npm package is an example; it is never loaded. Pass --config /path/to/mcp-config.json when you need a specific file.

Settings layer highest-to-lowest: CLI flags → mcp-config.json → built-in defaults. Only flags you actually type count as CLI input, so a config file still decides everything you left off the command line.

CLI flags

All config keys can be overridden at startup (highest priority):

pseudonym-mcp --lang pl --extra-locales de,it --sensitivity strict --engines regex

Claude Code

claude mcp add pseudonym-mcp -- npx -y pseudonym-mcp --engines hybrid

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pseudonym-mcp": {
      "command": "npx",
      "args": ["-y", "pseudonym-mcp", "--engines", "hybrid"]
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "pseudonym-mcp": {
      "command": "npx",
      "args": ["-y", "pseudonym-mcp", "--engines", "regex"]
    }
  }
}

Supported PII types

Detection is best-effort. The patterns below are what the tool looks for — not a guarantee of what it will always catch. See Limitations for known gaps.

Every table below is active on the default configuration. --lang switches packs off; see Locale coverage is fail-closed.

Custom literals

Custom literals are applied after the regex phase and before LLM NER, regardless of engine mode. Longest literals are matched first to prevent partial substitution.

How a match is decided

Every pattern carries a confidence score. A checksum that validates raises it, and a context word near the match — "PESEL:", "NIP", "Steuer-ID", "date of birth" — raises it too, enough on its own to reach the default threshold. What gets masked is whatever clears the sensitivity bar:

Where a failing checksum means "not this entity at all" (a card number failing Luhn), the candidate is dropped. Where it means a typo (a PESEL), the candidate survives at lower confidence — a mistyped identifier reaching the cloud is worse than a number masked for nothing.

Rules marked ✓ below verify a real check digit.

Global — active in every language

Polish (pl pack)

United States (en pack)

Other European locales

These run by default like every other pack. Narrow to a subset with --lang, or pair a chosen language with its neighbours using --extra-locales de,it — a Polish invoice carries German and Italian identifiers too.

Detected by the LLM, not by pattern

Language Detection

pseudonym-mcp includes a lightweight heuristic language detector based on franc. It infers the language from text content and returns a structured result:

detectLanguage('Umowa zostaje zawarta na czas nieokreślony')
// → { detected: 'pl', source: 'text', raw: 'pol', confidence: 0.94 }

detectLanguage('Hello')
// → { detected: 'unknown', source: 'fallback', raw: null, confidence: null }

Texts shorter than 20 characters or with low confidence return detected: 'unknown'. The detector does not affect the current pseudonymisation pipeline — --lang config remains authoritative. It is a building block for future multi-language and auto-select modes.

Engine modes

In hybrid mode, Ollama runs after the regex pass, so the local NER model receives already-tokenised structured identifiers. If Ollama is unreachable, the server logs a warning to stderr and returns the regex-only masked text — no crash, no hang.

Privacy & Security notes

Calibrated claims:

• No telemetry from the tool itself. pseudonym-mcp makes no network requests except to your local Ollama instance and (optionally) the MCP stdio transport.
• In-memory mapping by default. The mapping store is not written to disk. Sessions are scoped to the server process lifetime.
• Idempotent tokens within a session. The same original value always maps to the same token ([PERSON:1] will not become [PERSON:2] for the same name on a second occurrence), preserving semantic coherence in LLM reasoning.
• No model training. The local Ollama model operates offline. Your data is not used to train any model by this tool.
• Strict validation by default. Invalid SSNs (area 000/666/900+), failed-Luhn credit card numbers, and invalid-checksum PESELs are not masked, preventing false positives from OCR errors or random digit sequences.

What this does not guarantee:

• That all PII in your input is detected.
• That tokenised text is unlinkable to real people — re-identification from context is possible.
• That the cloud provider can't learn sensitive things from structure, timing, or content.
• Compliance with any specific regulation — that's a system-level property, not a tool-level one.

Limitations

pseudonym-mcp is a technical privacy control, not a legal guarantee of compliance.

• Detection is best-effort. False negatives and false positives are both possible. Indirect references (e.g. "the tall guy from accounting", "my landlord", "the place near the bridge") are not detected. Nicknames, initials, and partial names are typically missed.
• Structure still travels. Amounts, relationships between tokens, narrative content, and any PII the detector missed all reach the cloud LLM. Dates are masked only when they read as a date of birth, or at higher --sensitivity; the rest of the calendar goes through. Tokenisation hides who, not what kind of situation.
• Narrowing --lang narrows detection, silently at the source. With a locale pack switched off, its identifiers are not looked for at all — the output looks clean and the call still reports success. The server states which packs are off, on stderr and in every mask_text response; nothing downstream forces you to read it.
• Pre-mask logging is your problem. If your application logs plaintext before passing it to mask_text, this tool cannot help you.
• Process-local mapping. Restarting the server ends the session and discards mappings. This is intentional.
• Re-identification is possible for anyone with access to the local mapping store, and may be possible from context alone for anyone with side knowledge. This is pseudonymisation under GDPR Art. 4(5), not anonymisation.
• No legal advice. Nothing in this README constitutes legal advice. Compliance is a system-level property — talk to your DPO, your compliance team, and your lawyers about your specific deployment.

Under GDPR Art. 4(5) and Recital 26, pseudonymised data is still personal data. pseudonym-mcp substantially reduces cleartext PII exposure but does not eliminate your legal obligations.

Development

git clone https://github.com/woladi/pseudonym-mcp
cd pseudonym-mcp
npm install
npm run build    # tsc compile
npm test         # vitest (no Ollama required)

The test suite runs fully offline — Ollama calls are injected via constructor and mocked in all tests. No live LLM required.

Adding a recognizer

1. Add a file under src/patterns/locale/<lang>/ (or src/patterns/global/ if it is language-independent) exporting a PatternRule:

export const regonRule: PatternRule = {
  id: 'pl.regon',
  entityType: 'REGON',
  patterns: [
    { name: 'REGON (14 digits)', regex: /\b\d{14}\b/g, score: 0.25 },
    { name: 'REGON (9 digits)', regex: /\b\d{9}\b/g, score: 0.15 },
  ],
  locales: ['pl'],
  context: ['regon', 'nr regon', 'gus'],
  description: 'Polish business register number',
  validate: regonChecksum,
  checksumMode: 'boost',
}

2. Register it in the allPatterns array in src/patterns/index.ts. That is the only wiring — rule sets are derived from the registry by locale, so nothing else needs to know the rule exists.
3. For a brand-new language, add the locale to both SupportedLocale and SUPPORTED_LOCALES in src/patterns/types.ts — the default selection loads the list, so a pack missing from it never runs — plus the ISO 639-3 → short code mapping in src/language/language-map.ts. tests/default-coverage.test.ts fails if the two drift apart, and expects one specimen per pack.

Picking a score: start low and let evidence do the work. A shape that only appears as this entity (ABC123456, a codice fiscale) can start near 0.5. A run of digits that could be anything starts at 0.15–0.25 and relies on validate or on context to clear the bar.

Picking a checksumMode: filter when a failed check means it was never this entity (Luhn on a card), boost when it means a typo and a miss would leak data (PESEL, IBAN), gate when the check only rules out impossible values without confirming anything (US SSN ranges).

See src/patterns/locale/pl/ for worked examples of all three.

Contributing

Contributions are welcome. Please follow Conventional Commits for commit messages.

Releases run on changesets. If your change is user-visible, add a changeset to the PR:

npm run changeset   # pick patch / minor / major, describe the change

Merging to master then opens a "version packages" PR that bumps the version, server.json, src/version.ts and the changelog; merging that PR publishes to npm (Trusted Publishing, with provenance), tags the release, and refreshes the MCP registry entry. A merge with no pending changesets publishes nothing.

Language pack contributions are especially welcome — German (Personalausweis, Steuer-ID), French (NIR, SIRET), Spanish (DNI/NIE) and others would significantly expand the tool's usefulness.

License

MIT — Adrian Wolczuk