mcp-redact

中文 | English

本地优先的 CLI 和 MCP Server，用于在把日志、配置、报错等文本分享给 AI 工具之前，先自动脱敏敏感信息。

mcp-redact 只做一件事：在你把内容粘贴给 Claude Code、Cursor 或其他 AI 工具之前，先把 secret 和敏感数据脱敏。

为什么要做这个

开发者经常会把日志、.env 文件、请求头、报错堆栈、配置片段直接贴给 AI 工具。这些内容里很可能包含 API Key、Bearer Token、Cookie、邮箱地址等敏感值。

mcp-redact 的设计目标是让这件事更安全：

• 本地优先

• 基于正则、确定性的脱敏

• CLI 和 MCP 共用一套核心引擎

• 输出稳定、可解释，例如 [REDACTED_EMAIL]

脱敏前 / 脱敏后

脱敏前

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

脱敏后

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

快速开始

环境要求：

• Node.js 20+

• pnpm

安装依赖：

pnpm install

使用示例文件运行：

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

通过 stdin 管道输入：

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

示例文件

仓库内提供了可用于本地测试和演示的样例文件：

• examples/sample.log

• examples/sample.env

• examples/sample.json

• examples/sample.yaml

• examples/mcp-redact.config.json

所有样例值均为伪造数据。

CLI 用法

从 stdin 读取

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

从文件读取

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

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

写入输出文件

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

JSON 输出

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

示例输出：

{
  "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
    }
  }
}

只输出摘要

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

示例输出：

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

限制启用的规则组

只启用 personal 规则：

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

运行时禁用某个规则组：

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

使用配置文件

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

示例配置只启用 personal 和 custom 组，禁用内置 email detector，并新增一条 internal-ticket 自定义规则。由于 sample.log 里没有匹配的 ticket 且 email 脱敏被关闭，因此这个示例下文件内容不会发生变化。

MCP 用法

启动 MCP Server

开发模式：

pnpm mcp:dev

构建后运行：

pnpm build
pnpm mcp:start

MCP 工具

redact_text

输入：

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

redact_file

输入：

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

两个工具都会返回同样的结构：

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

从 MCP 客户端连接

根据你的环境选择对应的 server 命令：

• 开发模式：pnpm mcp:dev

• 构建产物：pnpm mcp:start

如果你的 MCP 客户端要求填写命令和参数，请指向本地项目并通过 stdio 启动服务。当前服务暴露两个工具：redact_text 和 redact_file。

配置

默认配置文件名：

mcp-redact.config.json

如果没有显式传入配置路径，mcp-redact 会尝试从当前工作目录读取这个默认文件。若默认文件不存在，程序会继续正常执行；如果你显式传入了一个不存在的配置路径，则命令会报错。

示例配置：

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

配置字段

• enabledGroups：限制只启用列出的内置或自定义规则组

• disabledDetectors：按名称禁用 detector，例如 email 或 github-token

• customRules：添加本地正则规则，并复用与内置规则相同的处理流水线

支持的内置 detector

secrets

• Bearer Token

• JWT

• GitHub Token

• OpenAI 风格 API Key

• Anthropic 风格 API Key

• AWS Access Key ID

• password=、token=、secret=、api_key= 这类键值形式 secret

• 多行私钥块

personal

• 邮箱地址

• 手机号

• IPv4 地址

http

• Authorization Header 中的 Bearer 值

• Cookie Header 中的敏感值

• URL 中敏感 query 参数，例如 token=

本地开发

常用命令：

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

路线图

• 增加更多 token 和 API key 模式

• 进一步降低误报

• 提供更多真实风格的日志和配置示例

• 提供更多端到端 MCP 客户端示例

English

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