pii-shield

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:

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

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