mcp-redact

Local-first CLI and MCP server for redacting sensitive text before sharing logs, configs, and errors with AI tools.

mcp-redact helps you do one thing before pasting text into Claude Code, Cursor, or other AI tools: redact secrets and sensitive data first.

Why this exists

Developers often paste logs, .env files, request headers, stack traces, and config snippets into AI tools. Those snippets can contain API keys, bearer tokens, cookies, emails, and other sensitive values.

mcp-redact is built to make that flow safer:

• local-first

• deterministic regex-based redaction

• shared engine for both CLI and MCP

• readable placeholders like [REDACTED_EMAIL]

Before / After

Before

Authorization: Bearer abcdefghijklmnop123456
user_email=user@example.com
callback=https://example.com/callback?token=secret123&lang=en
Cookie: session=abcdef123456; theme=dark

After

Authorization: Bearer [REDACTED_AUTHORIZATION_HEADER]
user_email=[REDACTED_EMAIL]
callback=https://example.com/callback?token=[REDACTED_SENSITIVE_URL]&lang=en
Cookie: session=[REDACTED_COOKIE_HEADER]; theme=dark

Quick start

Requirements:

• Node.js 20+

• pnpm

Install dependencies:

pnpm install

Run on a sample file:

pnpm dev -- --file ./examples/sample.log

Pipe text through stdin:

pnpm dev -- < ./examples/sample.log

Example files

This repository includes sample inputs you can use for local testing and demos:

• examples/sample.log

• examples/sample.env

• examples/sample.json

• examples/sample.yaml

• examples/mcp-redact.config.json

All sample values are fake.

CLI usage

Read from stdin

pnpm dev -- < ./examples/sample.log

Read from a file

pnpm dev -- --file ./examples/sample.log

pnpm dev -- --file ./examples/sample.env

Write output to a file

pnpm dev -- --file ./examples/sample.env --output ./sanitized.env

JSON output

pnpm dev -- --file ./examples/sample.log --format json

Example output:

{
  "redactedText": "Authorization: Bearer [REDACTED_AUTHORIZATION_HEADER]\nuser_email=[REDACTED_EMAIL]\ncallback=https://example.com/callback?token=[REDACTED_SENSITIVE_URL]&lang=en\nCookie: session=[REDACTED_COOKIE_HEADER]; theme=dark\n",
  "summary": {
    "totalMatches": 4,
    "byType": {
      "authorization_header": 1,
      "email": 1,
      "sensitive_url": 1,
      "cookie_header": 1
    }
  }
}

Summary-only output

pnpm dev -- --file ./examples/sample.log --summary-only

Example output:

Total matches: 4
By type:
- authorization_header: 1
- cookie_header: 1
- email: 1
- sensitive_url: 1

Limit enabled groups

Only run personal detectors:

pnpm dev -- --file ./examples/sample.log --only personal

Disable one group at runtime:

pnpm dev -- --file ./examples/sample.log --disable http

Use a config file

pnpm dev -- --file ./examples/sample.log --config ./examples/mcp-redact.config.json

The example config enables only personal and custom groups, disables the built-in email detector, and adds a custom internal-ticket rule. With that config, sample.log is left unchanged because it does not contain any custom ticket value and email redaction is disabled.

MCP usage

Start the MCP server

Development mode:

pnpm mcp:dev

Build and run:

pnpm build
pnpm mcp:start

MCP tools

redact_text

Input:

{
  "text": "Authorization: Bearer abcdefghijklmnop123456",
  "groups": ["http"],
  "configPath": "./examples/mcp-redact.config.json"
}

redact_file

Input:

{
  "filePath": "./examples/sample.log",
  "groups": ["http"],
  "configPath": "./examples/mcp-redact.config.json"
}

Both tools return the same structured shape:

{
  "redactedText": "...",
  "summary": {
    "totalMatches": 4,
    "byType": {
      "authorization_header": 1,
      "email": 1
    }
  }
}

Connecting from an MCP client

Use the server command that fits your environment:

• development: pnpm mcp:dev

• built output: pnpm mcp:start

If your MCP client expects a command plus arguments, point it at the local project and run the server over stdio. The server exposes two tools: redact_text and redact_file.

Configuration

Default config file name:

mcp-redact.config.json

If no explicit config path is provided, mcp-redact will try to read that file from the current working directory. If the default file is missing, execution continues normally. If you explicitly pass a missing config path, the command fails.

Example config:

{
  "enabledGroups": ["personal", "custom"],
  "disabledDetectors": ["email"],
  "customRules": [
    {
      "name": "internal-ticket",
      "pattern": "TICKET-[0-9]{6}",
      "placeholder": "[REDACTED_TICKET]"
    }
  ]
}

Config fields

• enabledGroups: restricts built-in and custom detectors to the listed groups

• disabledDetectors: disables detectors by name, such as email or github-token

• customRules: adds local regex-based detectors that use the same pipeline as built-in rules

Supported detectors

secrets

• Bearer token

• JWT

• GitHub token

• OpenAI-style API key

• Anthropic-style API key

• AWS access key id

• Key-value secrets like password=, token=, secret=, api_key=

• Private key blocks

personal

• Email

• Phone

• IPv4

http

• Authorization header bearer value

• Cookie header sensitive value

• Sensitive URL query value like token=

Local development

Common commands:

pnpm install
pnpm test
pnpm lint
pnpm typecheck
pnpm build
pnpm mcp:dev

Roadmap

• More token and API key patterns

• Better false-positive suppression

• More real-world log and config examples

• More end-to-end MCP client examples