pii-mcp

Pattern-based PII redaction for MCP servers (regex + checksums). Masks emails, IBANs, cards, BICs, MACs, IMEIs, IPs, coordinates, BSNs, US SSNs and ITINs, UK National Insurance and NHS numbers, German tax IDs, Dutch BTW-ids, Dutch and German passport/ID numbers, phones, street + house number addresses, Dutch and UK postcodes, and Dutch license plates in tool results. Also masks credentials (API keys, JWTs, Bearer tokens) as [SECRET]. Language packs: en, nl, and opt-in de.

If pii-mcp saves you time, a ⭐ helps others find it.

Example

from pii_mcp import scrub_text

scrub_text(
    "Contact ada@example.com. IBAN NL91 ABNA 0417 1643 00. card 4111111111111111"
)
# Contact [EMAIL]. IBAN [IBAN]. card [CREDIT_CARD]

For runnable scripts including a FastMCP server and payload scrubbing, see the examples/ directory.

Install

pip install "pii-mcp[fastmcp]"   # FastMCP >= 3.0.0
# or
pip install pii-mcp              # core; platform wheels include Rust acceleration
# or
npm install pii-mcp

FastMCP

from fastmcp import FastMCP
from pii_mcp.fastmcp import PiiScrubMiddleware

mcp = FastMCP("MyServer")
mcp.add_middleware(PiiScrubMiddleware())  # languages=["en", "nl"] by default
# mcp.add_middleware(PiiScrubMiddleware(languages=["en", "nl", "de"]))

Results only. On scrub failure or oversize, the result is withheld, never forwarded unmasked.

Core

from pii_mcp import scrub_text, scrub_payload

scrub_text("mail ada@example.com")
scrub_payload({"email": "ada@example.com"}, languages=["en"])
scrub_text("ops@foro.sh ada@example.com 123456782", types=["email"], allow=["ops@foro.sh"])
# ops@foro.sh [EMAIL] 123456782

types masks only the listed PiiType names (default: all). allow lists exact values (case-insensitive) left unmasked; it never exempts a secret. PiiScrubMiddleware takes both too.

Scope

Pattern Tier 1 only: structured identifiers that regex and checksums can reach. Aligned with AP: wat zijn persoonsgegevens where that layer applies. Free-text health data (allergies), photos/audio/ video, and unstructured klant-/personeelsnummers stay out of scope.

person is pattern / key-aware when available (issue #52); until then the count stays 0. Prose name NER is out of band — this package does not ship an in-process NER model. Decimal/DMS location coordinates stay here; free-text place names do not.

Using with foro / Presidio

Live MCP gates in user containers should run Tier 1 only (no model). On platforms such as foro, keep NER in one Presidio sidecar on API paths — do not stack a second in-process NER beside it.

AP coverage (pattern layer)

Packages

Tier 1 gate contract for foro user containers (caps, placeholders, binary skip): docs/tier1-gate.md.

Rust core (Python)

Published platform wheels ship pii_mcp._native (PyO3 over pii-core). Pip prefers those on supported OS/arch; elsewhere (or with --no-binary) you get the pure-Python hatchling wheel/sdist and the same scrub API.

When _native is importable, scrub_text / scrub_payload use it. Force the Python path with PII_MCP_BACKEND=python; require native with PII_MCP_BACKEND=native.

Local development from a clone (optional):

pip install -e ".[native]"
maturin develop --release --manifest-path crates/pii-mcp-native/Cargo.toml

Performance (Python vs Rust release)

Medians from scripts/bench_backends.py on macOS arm64 / CPython 3.14.7 (release native build; debug builds are not representative):

python scripts/bench_backends.py

Contributing

See CONTRIBUTING.md for setup, how to add a detector, and the checks a PR must pass.