pii-shield

Anonymize documents before Claude sees them. Restore real data after analysis.

---

PII Shield reads your documents locally, replaces all personal data with placeholders (<PERSON_1>, <ORG_1>, etc.), and — when you want analysis — sends only the anonymized text to an LLM. After analysis, PII Shield restores the original data into the final document — entirely on your machine. PII never enters the API.

Document ──> [PII Shield on your machine] ──> anonymized text ──> [LLM analyzes] ──> [PII Shield restores] ──> Result
              John Smith  → <PERSON_1>                                                <PERSON_1> → John Smith
              Acme Corp.  → <ORG_1>                                                   <ORG_1>    → Acme Corp.

Two ways to use it, sharing the same engine:

Form	Who it's for	Install
Standalone CLI (pii-shield)	Anyone — anonymize files locally for any LLM (or just for compliance / GDPR). Pure offline.	npm install -g pii-shield
Claude Desktop / Code extension (.mcpb + .skill)	Claude Desktop and Claude Code users — get tools + skill + in-chat HITL panel.	Drag the .mcpb from a release into Settings → Extensions, then upload the .skill

v2 is a complete Node.js rewrite. The original Python product is still available — see What happened to v1? below.

Features

	Feature	Details
🔒	Zero PII in API	anonymize_file reads the document on your machine and returns only a file path + session id. Claude reads the anonymized file from disk — PII never enters an API request.
🧠	GLiNER zero-shot NER	knowledgator/gliner-pii-base-v1.0 over onnxruntime-node + @xenova/transformers (pinned triplet 1.22.0, deterministic npm ci). Handles ALL-CAPS, domain-specific names, multilingual text. No Python, no PyTorch.
👤	Human-in-the-Loop review	MCP Apps iframe UI rendered directly in Claude Desktop. Remove false positives, add missed entities — all occurrences updated automatically, no localhost browser detour.
📄	PDF + DOCX + plain text	.pdf, .docx (formatting + tracked changes preserved), .txt, .md, .csv. Pure-JS .docx pipeline — reads, edits, restores without a Word / LibreOffice install.
🇪🇺	EU + UK pattern recognizers	UK (NIN, NHS, passport, CRN, driving licence), DE (tax ID, social security), FR (NIR, CNI), IT (fiscal code, VAT), ES (DNI, NIE), CY (TIC, ID card), FI (henkilötunnus, Y-tunnus), EU-wide (VAT, passport) — on top of the generic pack (email, phone, IBAN, credit card, crypto, US IDs, medical licence). 35 entity types in total.
🔗	Entity deduplication	"Acme" → <ORG_1>, "Acme Corp." → <ORG_1a>, "Acme Corporation" → <ORG_1b>. Canonical form picked once; every variant maps back to the same real value on deanonymize.
💾	Cross-session deanonymize	Each anonymized .docx carries its session_id in Word custom properties. Weeks later, in a brand new chat, drop the file in and deanonymize_docx restores PII from the embedded id — nothing to remember.
📦	Multi-file sessions	Anonymize N related documents under one session_id; identical entities share the same placeholder across files. One deanonymize_text / deanonymize_docx call restores PII everywhere.
🤝	Team handoff	export_session(passphrase) packs the mapping + anonymized documents into an encrypted .pii-session archive (AES-GCM via scrypt). Colleague runs import_session with the passphrase — PII never transits.
📊	Audit logging	Every tool call + response logged locally to ~/.pii_shield/audit/mcp_audit.log. NER bootstrap trace, session lifecycle, dropped stderr — all on disk, appendable, off-network.

Standalone CLI — pii-shield

If you don't use Claude Desktop / Claude Code, install the CLI globally and run it on any file. Works on 20–30 documents in one session with shared placeholders across files.

npm install -g pii-shield

pii-shield doctor                                       # health check
pii-shield install-model                                # download GLiNER (~634 MB, one-off)

# anonymize one file
pii-shield anonymize contract.pdf --no-review

# anonymize a batch — same session_id, same placeholders for shared entities
pii-shield anonymize contracts/*.pdf attachments/*.docx

# review opens a browser (localhost:6789) with the bulk-mode panel
pii-shield review 2026-04-29_101617_9f40

# restore PII back when you're done
pii-shield deanonymize contract_anonymized.pdf --session 2026-04-29_101617_9f40

Command	What it does
pii-shield anonymize <files…>	Anonymize one or many files in one session. Shared placeholders across files.
pii-shield deanonymize <file>	Restore PII. Session id read from .docx metadata, --session, or latest.
pii-shield scan <file> [--json]	Preview detected entities without writing anything.
pii-shield review <session-id>	Re-open the HITL review panel for a session.
pii-shield sessions list / show / export / import	Inspect and hand off sessions across machines.
pii-shield install-model [--yes]	Download/extract the GLiNER ONNX model.
pii-shield doctor [--json]	Check Node, deps, model, paths.

The CLI uses the same engine, mappings, and audit log as the MCP variants. Sessions are interchangeable: anonymize on the CLI, deanonymize from Claude Desktop, or vice versa — the mapping store is shared (~/.pii_shield/mappings/). Requires Node 22+.

Claude Desktop / Claude Code

Prerequisites

• Claude Desktop (any recent version)
• Windows or Linux: Claude Desktop ships a compatible Node runtime. Nothing to install separately.
• macOS: the macOS .mcpb below bundles its own Node 24.15.0. Nothing to install separately.

No terminal commands. No model download upfront. PII Shield handles model install in-chat via a panel that appears the first time you anonymize.

Step 1 — download the artefacts

Pick the .mcpb for your OS plus the skill bundle:

File	What	OS
pii-shield-v2.2.0-windows-linux.mcpb	~700 KB — uses host Node	Windows / Linux
pii-shield-v2.2.0-macos.mcpb	~83 MB — bundles Node 24.15.0	macOS (arm64 + x64)
pii-contract-analyze.skill	~25 KB — contract analysis skill	any

Step 2 — install the MCP extension

Claude Desktop → Settings → Extensions → Advanced Settings → Install extension → select your .mcpb.

On the first tool call PII Shield runs npm ci --ignore-scripts to install a pinned, deterministic set of runtime deps (onnxruntime-node, @xenova/transformers, gliner) into ~/.pii_shield/deps/installs/<slug>/. 2–3 minutes once per machine, instant thereafter.

Step 3 — upload the skill

Claude Desktop → Customize → Skills → + → Upload a skill → select pii-contract-analyze.skill.

The skill orchestrates the end-to-end contract anonymization + analysis flow — Claude uses it to drive anonymize_file → HITL review → analysis → deanonymize_docx without you spelling out each step.

Step 4 — use it

1. Start a new conversation in Claude Desktop
2. Select the pii-contract-analyze skill
3. Connect a folder containing your document (click the folder icon)
4. Tell Claude what you need:

Analyze risks for the purchaser in contract.pdf and prepare a short memo

First-run install panel

The very first time you ask Claude to anonymize anything, PII Shield notices the NER model isn't on disk yet and opens an in-chat install panel. You see two buttons:

1. Download model — opens your default browser, downloads gliner-pii-base-v1.0.zip (~634 MB) from the release. Browser handles the transfer (no Defender / SmartScreen issues with unsigned scripts).
2. Install downloaded ZIP — PII Shield finds the ZIP in your Downloads / OneDrive / Desktop / Documents folder, validates it, atomic-extracts it into ~/.pii_shield/models/, and re-initializes NER. Anonymization continues automatically.

No terminal, no scripts. Subsequent runs skip the panel entirely.

⚠️ Do NOT attach files directly to anonymize. When you attach a file, Claude Desktop sends its content in the API request — Claude sees raw data before PII Shield can process it. Connect a folder instead — Claude only gets the file path and calls anonymize_file locally.

Privacy architecture

Only file paths and random session IDs flow through the API. All anonymization and restoration happens locally.

Stage	What happens	PII in API?
Anonymize	Server reads file on host, writes anonymized text to disk, returns output_path	❌
Claude reads	Claude reads anonymized .txt — only sees placeholders	❌
Review	User reviews entities in MCP Apps iframe (rendered in Claude Desktop)	❌
Re-anonymize	Server applies user corrections internally	❌
Deanonymize	Server writes restored file to disk, returns only the path	❌
Deliver	Claude gives user the file path. Never reads the restored file.	❌

Human-in-the-Loop review

After anonymization, Claude offers a review step rendered directly in Claude Desktop via MCP Apps:

1. Claude calls start_review — Claude Desktop opens a panel inside the conversation
2. Full document with color-coded entity highlights
3. Remove false positives — click any entity (all occurrences removed)
4. Add missed entities — select text, choose type (all occurrences added)
5. Approve — Claude calls apply_review_overrides, the server re-anonymizes with your corrections

No localhost web server, no browser detours — the UI is a Vite single-file iframe served to Claude Desktop as a ui:// MCP resource.

Cross-session deanonymize

Every anonymized .docx PII Shield writes carries its session_id inside Word custom document properties (docProps/custom.xml). Later, in a brand new chat, you can:

1. Drop the anonymized .docx into a connected folder — no need to remember the session id, no screenshots of placeholders, nothing.
2. Ask Claude to "restore PII in this file."
3. PII Shield's deanonymize_docx reads the embedded session_id, looks up the mapping in ~/.pii_shield/mappings/, and writes the restored file next to the input.

Mappings live at ~/.pii_shield/mappings/ — same root as models/, deps/, and audit/. The root survives plugin upgrades and /plugin remove because it's in the user's home dir, not Claude Desktop's per-plugin CLAUDE_PLUGIN_DATA (which isn't set for MCPB plugins anyway).