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