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

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
.github/workflows		.github/workflows
examples		examples
plan		plan
src		src
test		test
.gitignore		.gitignore
.prettierrc.json		.prettierrc.json
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
eslint.config.js		eslint.config.js
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

mcp-redact

为什么要做这个

脱敏前 / 脱敏后

脱敏前

脱敏后

快速开始

示例文件

CLI 用法

从 stdin 读取

从文件读取

写入输出文件

JSON 输出

只输出摘要

限制启用的规则组

使用配置文件

MCP 用法

启动 MCP Server

MCP 工具

redact_text

redact_file

从 MCP 客户端连接

配置

配置字段

支持的内置 detector

secrets

personal

http

本地开发

路线图

English

Why this exists

Before / After

Before

After

Quick start

Example files

CLI usage

Read from stdin

Read from a file

Write output to a file

JSON output

Summary-only output

Limit enabled groups

Use a config file

MCP usage

Start the MCP server

MCP tools

redact_text

redact_file

Connecting from an MCP client

Configuration

Config fields

Supported detectors

secrets

personal

http

Local development

Roadmap

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`redact_text`

`redact_file`

`secrets`

`personal`

`http`

`redact_text`

`redact_file`

`secrets`

`personal`

`http`