Redact MCP — Automatic PII Obfuscation for Claude Code

An MCP server (and Claude Code plugin) that automatically detects and obfuscates sensitive data before Claude ever sees it. Uses regex pattern matching and AI-powered Named Entity Recognition (NER) to catch IPs, hostnames, emails, API keys, person names, organization names, locations, private keys, connection strings, and more.

Built for penetration testers who need Claude's analysis capabilities without exposing client data to a third party.

How It Works

Raw data with real PII ──► Regex + NER detection ──► Claude sees only fake values
                                                              │
Final report for client ◄── Real values restored ◄── /redact:export

The server maintains a bidirectional mapping table. Every sensitive value gets a consistent, deterministic fake replacement that persists across the entire session:

| Real Value | Obfuscated As | Detection | |---|---|---| | 10.50.1.100 | 198.51.100.1 | regex | | api.clientcorp.com | target-1.example.com | regex | | john.smith@clientcorp.com | user-1@example.com | regex | | AKIA3EXAMPLE... | [REDACTED_AWS_KEY_1] | regex | | James Wilson | Person_A Person_B | NER | | Microsoft | Org_A | NER | | Seattle | City_A | NER | | postgres://admin:pw@host/db | [REDACTED_CONN_STRING_1] | regex | | -----BEGIN RSA PRIVATE KEY... | [REDACTED_PRIVATE_KEY_1] | regex |

Same real value always maps to the same fake value. obfuscate(text) -> deobfuscate(result) === text is guaranteed.

Install

Quick install via npx (recommended)

claude mcp add @mattzam/redact-mcp -- npx @mattzam/redact-mcp

That's it. Claude Code will launch the server via npx on each session. The NER model (~110MB) downloads automatically on first use and is cached for subsequent runs.

To enable audit logging:

claude mcp add @mattzam/redact-mcp -e REDACT_AUDIT_LOG=true -- npx @mattzam/redact-mcp

As a Claude Code plugin (full features: hooks + skills)

git clone https://github.com/r3352/redact-mcp.git redact
cd redact/server
npm install
npm run build
cd ../..

# Load as a plugin (includes hooks for leak detection + slash commands)
claude --plugin-dir ./redact

The plugin mode adds hooks (automatic leak detection on raw tool output) and skills (/redact:status, /redact:add, /redact:export) on top of the MCP server.

Manual MCP configuration

Add to your Claude Code MCP config (~/.claude/mcp.json or project .mcp.json):

{
  "mcpServers": {
    "redact-server": {
      "command": "npx",
      "args": ["redact-mcp"],
      "env": {
        "REDACT_DATA_DIR": "/path/to/data/directory",
        "REDACT_AUDIT_LOG": "true"
      }
    }
  }
}

Environment Variables

| Variable | Default | Description | |---|---|---| | REDACT_DATA_DIR | ./data | Directory for mapping state and audit logs | | REDACT_AUDIT_LOG | false | Set to true to enable JSONL audit logging |

What Gets Detected

Regex Patterns (19 types)

Zero configuration required. Detected automatically:

| Category | Types | |---|---| | Network | IPv4 (private + public), IPv6, hostnames with valid TLDs, MAC addresses | | Identity | Emails, person names (JSON context), phone numbers (US + international), SSNs | | Secrets | AWS access keys, JWTs, Bearer tokens, API keys (context-aware), generic secrets (password=, secret=), private keys (PEM format), connection strings (postgres/mysql/redis/mongodb/amqp/mssql URIs) | | Financial | Credit card numbers (Luhn-validated) | | Physical | Street addresses (123 Main Street, 456 Oak Ave, etc.) |

NER Detection (AI-powered)

When @huggingface/transformers is installed (included by default), the server loads Xenova/bert-base-NER (~110MB ONNX model, downloaded on first use) to detect:

| Entity Type | Example | Obfuscated As | |---|---|---| | Person names | James Wilson | Person_A Person_B | | Organizations | Microsoft, Acme Corp | Org_A, Org_B | | Locations | Seattle, New York | City_A, City_B |

NER catches entities that regex misses — names and organizations outside of JSON context, arbitrary location names, etc. Regex results always take priority when both detect the same span (regex is more precise for structured patterns).

Graceful fallback: If the model fails to load or the package is missing, the server continues in regex-only mode with no errors.

Smart Passthrough

These values are never obfuscated:

• Loopback/reserved: localhost, 127.0.0.1, ::1, 0.0.0.0
• RFC documentation ranges: 192.0.2.x (TEST-NET-1), 198.51.100.x (TEST-NET-2), 203.0.113.x (TEST-NET-3), 2001:db8:: (IPv6 docs)
• Example domains: example.com, example.org, example.net
• Dev domains: github.com, npmjs.com, nodejs.org, googleapis.com, etc.
• Security testing: burpcollaborator.net, oastify.com
• Code patterns: console.log, process.env, package.json, webpack.config, jest.config, tailwind.config, and 30+ other common false positives
• Broadcast MACs: FF:FF:FF:FF:FF:FF, 00:00:00:00:00:00

MCP Tools

The server registers 8 tools via MCP:

| Tool | Description | |---|---| | redact_obfuscate | Auto-detect and replace all PII in text (regex + NER) | | redact_deobfuscate | Reverse all replacements back to real values | | redact_proxy_request | HTTP proxy — deobfuscates request, makes real call, obfuscates response | | redact_read_file | Read a file and return obfuscated content | | redact_add_mapping | Manually add a real-to-fake mapping | | redact_remove_mapping | Remove a mapping (fix false positives) | | redact_show_mappings | Show all current mappings grouped by type | | redact_audit_log | View recent audit log entries (requires REDACT_AUDIT_LOG=true) |

redact_proxy_request — The Key Tool

For pentest workflows, this is the critical tool. Claude calls it instead of curl/fetch:

1. Claude provides URL/headers/body (may contain already-obfuscated values)
2. Server deobfuscates the request (restores real hostnames/IPs/tokens)
3. Makes the real HTTP request to the target
4. Obfuscates the entire response (headers + body)
5. Returns sanitized response to Claude

Claude never sees the real response data. All deobfuscation and obfuscation steps are audit-logged.

redact_audit_log — Compliance Audit Trail

When REDACT_AUDIT_LOG=true, every obfuscation and deobfuscation operation is logged to ${REDACT_DATA_DIR}/audit.jsonl. Each entry records:

• Timestamp and operation type (obfuscate, deobfuscate, proxy_request, file_read)
• Full input text (raw data before transformation)
• All detections with type, real value, fake replacement, and source (regex or ner)
• Full output text (transformed result)

This provides a complete audit trail: what went in, what was modified, and what came out.

View entries via the redact_audit_log tool or read audit.jsonl directly:

# Last 5 entries, pretty-printed
tail -5 data/audit.jsonl | python3 -m json.tool

Security note: The audit log contains real sensitive data by design (that's its purpose — proving what was redacted). Protect it accordingly.

Skills (Slash Commands)

| Command | Description | |---|---| | /redact:status | Show current redaction mappings grouped by type | | /redact:add <real> <fake> | Manually add a mapping (e.g., /redact:add clientcorp.com target.example.com) | | /redact:export <file> [output] | Deobfuscate a file for client delivery (defaults to ~/Desktop/) |

Hooks

The plugin uses two hooks (automatic, no user interaction):

• SessionStart — Injects instructions telling Claude to route all data through redact tools
• PostToolUse — Warns if Claude uses raw Bash/Read/Grep/WebFetch and the output contains known sensitive values (leak detection)

How the Pipeline Works

Detection

1. Regex pass — 19 pattern types scanned synchronously via compiled RegExp
2. NER pass — Xenova/bert-base-NER runs in parallel (async), catches person/org/location entities
3. Merge — Results combined; regex matches win on overlapping spans (more precise for structured data)
4. Deduplication — Overlapping NER results that cover the same span as a regex match are dropped

Mapping

1. Each unique real value gets a deterministic fake via counter-based generation
2. Fake values use safe ranges: TEST-NET-2 for IPv4, RFC 3849 for IPv6, example.com for domains, 555 prefix for phones, locally-administered range for MACs
3. Mappings persist to ${REDACT_DATA_DIR}/mappings.json with debounced writes (500ms)
4. Longest-first replacement prevents partial match corruption (e.g., 10.50.1.100 before 10.50.1.10)

Round-trip Guarantee

deobfuscate(obfuscate(text)) === text for all inputs. The bidirectional mapping table ensures lossless restoration.

Architecture

redact/
├── .claude-plugin/plugin.json     # Plugin manifest
├── .mcp.json                      # MCP server config (stdio transport)
├── hooks/
│   ├── hooks.json                 # Hook definitions
│   └── scripts/
│       ├── session-start.sh       # Injects redaction context on session start
│       └── post-tool-scan.py      # Leak detection on raw tool output
├── skills/
│   ├── status/SKILL.md            # /redact:status
│   ├── add/SKILL.md               # /redact:add
│   └── export/SKILL.md            # /redact:export
└── server/
    ├── package.json               # v2.0.0, deps: @modelcontextprotocol/sdk, @huggingface/transformers
    ├── tsconfig.json              # ES2022, Node16 modules, strict
    └── src/
        ├── index.ts               # MCP server — 8 tools, server instructions
        ├── mapping-engine.ts      # Bidirectional mapping, async obfuscate/deobfuscate, audit integration
        ├── pattern-detector.ts    # 19 regex patterns + async NER merge
        ├── fake-generator.ts      # Deterministic counter-based fake value generation
        ├── ner-detector.ts        # Lazy-loaded HuggingFace NER with graceful fallback
        ├── audit-logger.ts        # JSONL append logger, serialized write queue
        └── persistence.ts         # JSON state file with debounced writes

Runtime Flow

Claude Code ──stdio──► MCP Server (index.ts)
                            │
                     CallToolRequest
                            │
                    ┌───────┴───────┐
                    │ MappingEngine │
                    └───────┬───────┘
                            │
              ┌─────────────┼─────────────┐
              │             │             │
        detectPatterns   NER detect   AuditLogger
        (regex, sync)   (async)      (JSONL, async)
              │             │             │
              └─────────────┼─────────────┘
                            │
                     merge + dedupe
                            │
                     apply mappings
                     (longest-first)
                            │
                     return to Claude

Development

cd server

# Install dependencies (~110MB for NER model on first run)
npm install

# Build TypeScript
npm run build

# Test MCP server starts and lists tools
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | node dist/index.js

# Quick obfuscation test
node -e '
const { MappingEngine } = await import("./dist/mapping-engine.js");
const engine = new MappingEngine("/tmp/redact-dev");
await engine.init();
console.log(await engine.obfuscate("Email john@acme.com from 10.0.0.1"));
'

Changelog

v2.0.0

• NER detection — AI-powered entity recognition via @huggingface/transformers + Xenova/bert-base-NER. Catches person names, organizations, and locations outside structured JSON context.
• Audit logging — Opt-in JSONL audit trail (REDACT_AUDIT_LOG=true) records full input/output text, all detections with sources, and timestamps for every obfuscation and deobfuscation operation.
• 7 new pattern types — organization, location, private_key, connection_string, generic_secret, mac_address, street_address
• 8th tool — redact_audit_log for viewing audit entries
• Improved phone detection — International format support (+CC-XXXX-XXXX)
• Expanded false positive list — webpack.config, jest.config, tailwind.config, and 9 other config file patterns

v1.0.0

• Initial release with regex-only detection (12 pattern types), 7 MCP tools, bidirectional mapping, persistence, hooks, and skills.

License

MIT