pii-mcp

Pattern-based PII scrubbing for MCP servers (regex + checksums). Mask emails, IBANs, cards, BICs, MACs, IMEIs, IPs, coordinates, BSNs, US SSNs, German tax IDs, Dutch BTW-ids, Dutch passport/ID numbers, phones, Dutch postcodes, and Dutch license plates in tool results — not NER for person names or full street addresses. Language packs: en, nl, and opt-in de.

Aligned with AP: wat zijn persoonsgegevens where pattern/checksum detection can reach them. Names, free-text health data (allergies), photos/audio/video, unstructured klant-/personeelsnummers, and full street addresses need NER or media handling and stay out of scope.

AP coverage (pattern layer)

Packages:

Install (Python)

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

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

FastMCP (Python)

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 (Python)

from pii_mcp import scrub_text, scrub_payload

scrub_text("mail ada@example.com")
scrub_payload({"email": "ada@example.com"}, languages=["en"])

Install (TypeScript)

npm install pii-mcp

Default installs stay pure TypeScript. To use the same pii-core crate via N-API from a clone of this repo (shared with Python’s PyO3 addon):

cd typescript
npm install
npm run build
npm run build:native   # requires a Rust toolchain; needs ../crates/pii-core

Published npm install pii-mcp is JS-only until optional native artifacts ship. When a locally built napi addon is loadable, scrubText / scrubPayload use it. Force the JS path with PII_MCP_BACKEND=js. See typescript/README.md.

Performance (TypeScript vs Rust release)

Medians from scripts/bench_backends.mjs on macOS arm64 / Node 22 (release napi build). V8 is already fast, so napi wins are modest on larger/mixed inputs; tiny calls can favor pure JS (FFI overhead):

cd typescript && npm run build && npm run build:native
node ../scripts/bench_backends.mjs

Core (TypeScript)

import { scrubText, scrubPayload, usingNative } from "pii-mcp";

scrubText("mail ada@example.com");
scrubPayload({ email: "ada@example.com" }, { languages: ["en"] });
usingNative();