MCP Secret Scan

Find secrets before they reach a commit.

MCP Secret Scan checks staged diffs, files, directories, and raw text for API keys, tokens, private keys, passwords, and high-entropy strings — with masked findings and severity-based exit codes that work as a pre-commit or CI gate. Use it as an MCP tool so an agent can scan its own work before committing, or straight from the terminal. Fully offline: nothing you scan leaves your machine.

Fifth tool in the TokenSaver family: TokenSaver MCP maps repositories, MCP Context Budget audits tool costs, MCP Web Snapshot reads the web, MCP Log Tail summarizes logs, and Secret Scan guards commits.

Product requirements: PRD.md · PRD.id.md (Bahasa Indonesia)

Why

Secrets leak through commits far more often than through breaches: an .env pasted into a config, a token in a test fixture, credentials in a database URL. Linters and tests do not catch them, and by the time a scanner runs in CI the secret is already in history. The cheapest fix is a gate right before the commit — and that gate should be callable by the agent doing the work.

Related MCP server: Security & GRC MCP Server

Quick start

CLI, no install needed. Scan staged changes:

npx -y mcp-secret-scan scan --staged

Example output:

# Secret scan: staged changes

2 finding(s) in 1 file(s) — CRITICAL 1, HIGH 1

CRITICAL src/config.ts:12:15  aws-access-key — AWS access key id
  const key = "AKIA…MPLE";
HIGH     src/db.ts:4:20        uri-credentials — Password embedded in a URI
  const url = "postgres://admin:****@db.example.com/app";

All secrets are masked. Nothing leaves your machine.
Gate: FAILED — this would block a commit.

Other modes:

npx -y mcp-secret-scan scan ./src --strict
npx -y mcp-secret-scan text --content "AWS_KEY=AKIAIOSFODNN7EXAMPLE"
npx -y mcp-secret-scan scan --range main..HEAD --json

Exit codes: 0 clean, 1 findings at or above the threshold (critical/high by default, medium with --strict), 2 usage error. That makes it a drop-in pre-commit hook.

MCP server

Add it to any MCP-compatible client:

{
  "mcpServers": {
    "secretscan": {
      "command": "npx",
      "args": ["-y", "mcp-secret-scan", "serve"]
    }
  }
}

From a local checkout, point command at node and args at the built entry point:

{
  "mcpServers": {
    "secretscan": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-secret-scan/dist/index.js", "serve"]
    }
  }
}

Tools

Every tool returns masked findings classified as critical, high, medium, or low. The full secret is never printed.

What it detects

• Cloud and platform keys: AWS access key ids, Google API keys.

• Developer tokens: GitHub (ghp_, gho_, github_pat_), npm, PyPI, Slack, Stripe, SendGrid, Twilio.

• AI provider keys: OpenAI (sk-), Anthropic (sk-ant-).

• Credentials: private key blocks, passwords embedded in URIs, JWTs.

• Unlabeled secrets: high-entropy strings with mixed character classes.

• Generic assignments: api_key = "...", password: "...", and similar patterns.

False positives are first-class

• Inline // secret-scan:ignore (or # secret-scan:ignore) skips a line.

• .secretscanignore in the working directory holds allowlist regexes, one per line.

• --allow <regex> adds allowlist patterns per run; repeatable.

• Placeholders like your_api_key_here, example, xxxx, or changeme are ignored.

• Generic matches are medium and never block unless --strict is set.

Design principles

• Offline: no network, no telemetry, no secret ever transmitted or logged in full.

• Bounded: file size caps, directory ignore list, binary detection, and a findings cap.

• Read-only: never edits files, never writes history.

• Fast: pure regex and entropy checks, no model calls.

• Gate-friendly: severity thresholds and exit codes designed for hooks and CI.

CLI reference

Pre-commit example

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: secret-scan
        name: secret scan
        entry: npx -y mcp-secret-scan scan --staged
        language: system
        pass_filenames: false

Roadmap

• Custom rule files per project.

• Baseline mode: accept existing findings and only block new ones.

• Git history scan for auditing past commits.

• SARIF output for code scanning integrations.

• Configurable entropy thresholds.

Development

npm install
npm run typecheck
npm run build
npm test

The suite covers every rule, masking, entropy detection, allowlists, git diff parsing with real repositories, directory walking, CLI behavior, and MCP round trips.

License

MIT — see LICENSE.