gregmos/pii-shield

🛡️ 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 (, , 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  →                                                  → John Smith
              Acme Corp.  →                                                        → Acme Corp.

Two ways to use it, sharing the same engine:

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

Features

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

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:

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//. 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.

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).

Time-based TTL is controlled by PII_MAPPING_TTL_DAYS (default: 7 days) — the server cleans up mappings older than that on startup. Bump it for longer-lived matters (PII_MAPPING_TTL_DAYS=90, etc.) via Claude Desktop → Extensions → PII Shield → Settings. If a mapping is missing when you try to deanonymize, deanonymize_docx returns a clean error with a hint to import_session (see Team handoff below) rather than silently skipping entities.

Plain .txt / .md output has no place to embed metadata, so the deanonymize_text tool takes the session_id explicitly as an argument.

Multi-file sessions

Anonymize several related documents under one session_id:

1. First call: anonymize_file(path_A) — server returns session_id=SID123.
2. Second call: anonymize_file(path_B, session_id="SID123") — PII Shield extends the same mapping. Identical entities across the two files share the same placeholder (Acme Corp. becomes `` in both).
3. You write a memo in Claude that mixes placeholders from both files.
4. One deanonymize_text(..., session_id="SID123") call on the memo restores PII everywhere.

The pii-contract-analyze skill drives this automatically when the user uploads N ≥ 2 files and confirms they belong to one matter. See plugin/skills/pii-contract-analyze/references/bulk-mode.md for the full decision tree.

Team handoff — export / import a session

If a colleague needs to work on the same documents without you re-sharing PII:

1. You call export_session(session_id, passphrase) — server packs the mapping + anonymized documents into an encrypted .pii-session archive (AES-GCM with a key derived from the passphrase via scrypt).
2. Send them the .pii-session file (email, Slack, thumb drive — it’s useless without the passphrase).
3. They call import_session(path, passphrase) on their machine — the mapping lands under their ~/.pii_shield/mappings/ and they can now deanonymize_docx locally.

PII never leaves the anonymized documents in transit. The archive format is versioned (.pii-session v1), so future schema changes will stay readable.

MCP tools

Skill modes

The included pii-contract-analyze skill supports:

Detected entity types

Authoritative list is nodejs-v2/src/engine/entity-types.ts (SUPPORTED_ENTITIES).

NER-based (GLiNER zero-shot over ONNX Runtime): PERSON, ORGANIZATION, LOCATION, NRP

Generic pattern-based: EMAIL_ADDRESS, PHONE_NUMBER, URL, IP_ADDRESS, ID_DOC, CREDIT_CARD, IBAN_CODE, CRYPTO, MEDICAL_LICENSE

US: US_SSN, US_PASSPORT, US_DRIVER_LICENSE

UK: UK_NHS, UK_NIN, UK_PASSPORT, UK_CRN, UK_DRIVING_LICENCE

EU-wide: EU_VAT, EU_PASSPORT

Country-specific: DE_TAX_ID, DE_SOCIAL_SECURITY, FR_NIR, FR_CNI, IT_FISCAL_CODE, IT_VAT, ES_DNI, ES_NIE, CY_TIC, CY_ID_CARD, FI_HETU, FI_BUSINESS_ID

35 types total (4 NER + 31 pattern-based).

Logs

Development

All code lives in nodejs-v2/. From that directory:

# Install exact-pinned dev deps
npm ci --ignore-scripts --legacy-peer-deps

# Type-check
node node_modules/typescript/bin/tsc --noEmit

# Build the thin .mcpb (Windows / Linux + darwin via platform overrides)
npm run build:plugin

# Also build the darwin-universal .mcpb (downloads Node 24.15.0 arm64 + x64)
npm run build:plugin:mac

# MCP protocol smoke test
npm run smoke

# Focused clean-install smoke for the sharp shim + transformers + gliner
npm run smoke:sharp-shim

Troubleshooting

What happened to v1?

v1.0.0 was a Python MCP server built on presidio + SpaCy + GLiNER/py, shipped as a .dxt bundle. It’s still available:

• Tag v1.0.0 — pinned source.
• Branch python-legacy — full tree before the Node.js rewrite.

v2 is a complete architectural reset — Node.js, pure-JS .docx, MCP Apps UI, thin .mcpb — not a drop-in upgrade.

Acknowledgments

PII Shield builds on excellent open-source projects:

• GLiNER + knowledgator/gliner-pii-base-v1.0 — zero-shot NER backbone.
• onnxruntime-node — the CPU inference engine.
• @xenova/transformers — tokenizer + HF weights loader on top of ONNX Runtime.
• docx + jszip + @adeu/core — pure-JS .docx read / write / track-changes.
• Claude Desktop + the Model Context Protocol — host runtime and tool surface.

Author

Grigorii Moskalev — LinkedIn

License

MIT