# secretscan-mcp-server

[![Glama score](https://glama.ai/mcp/servers/wedo911/secretscan-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/wedo911/secretscan-mcp-server)

An [MCP](https://modelcontextprotocol.io) server that scans a diff, a
file's contents, or a pasted snippet for accidentally-committed secrets --
so any MCP-compatible agent can self-check its own changes before
committing, opening a PR, or pasting a log excerpt anywhere. Fully local:
no API key, no network call, no dependency beyond the MCP SDK and Zod.

## Why

A leaked credential is one of the most common real-world causes of account
and infrastructure compromise, and one of the easiest mistakes to make in a
large diff -- a debug `console.log` with a real API key, a config file
committed by accident, a `.env` pasted into a chat while asking for help.
An agent that's about to commit, push, or share text is well positioned to
catch this *before* it happens, if it has a cheap way to check.

## Tool

### `scan_for_secrets`

Scans text against a fixed set of provider-format signatures plus a
generic, entropy-gated heuristic:

| Detector | Catches |
|---|---|
| `aws_access_key_id` | AWS access key IDs (`AKIA...`) |
| `aws_secret_access_key` | AWS secret keys, when contextually labeled |
| `github_personal_access_token` / `github_fine_grained_token` | GitHub PATs (`ghp_...`, `github_pat_...`) |
| `slack_token` | Slack tokens (`xoxb-...`, etc.) |
| `stripe_live_key` / `stripe_test_key` | Stripe secret/publishable keys |
| `google_api_key` | Google API keys (`AIza...`) |
| `npm_token` | npm publish tokens (`npm_...`) |
| `private_key_block` | PEM private key blocks |
| `jwt` | JSON Web Tokens |
| `generic_assigned_secret` | anything assigned to a secret-sounding variable name (`api_key`, `password`, `token`, ...) whose value has high enough [Shannon entropy](src/services/entropy.ts) to look random rather than a placeholder like `"changeme"` |

**Findings are always redacted** -- `AKIAIOSFODNN7EXAMPLE` is reported as
`AKIA************MPLE (20 chars)`, never in full. The tool's own output is
therefore safe to log or display without further propagating whatever it
found.

This is a fixed-pattern + heuristic scan, not exhaustive. A clean result
means "no known pattern matched," not "definitely safe" -- the in-app
output says so explicitly.

## Install and configure

```bash
git clone https://github.com/wedo911/secretscan-mcp-server.git
cd secretscan-mcp-server
npm install
npm run build
```

Add it to your MCP client's config (e.g. `claude_desktop_config.json`, or a
project's `.mcp.json` for Claude Code):

```json
{
  "mcpServers": {
    "secretscan": {
      "command": "node",
      "args": ["/absolute/path/to/secretscan-mcp-server/dist/index.js"]
    }
  }
}
```

## Run the tests

```bash
npm run build
node --test tests/entropy.test.mjs tests/detectors.test.mjs
```

24 tests, including one for every named detector, the placeholder- and
low-entropy-filtering behavior of the generic detector, and an explicit
check that redacted output never contains the full secret value.

## Try it without a client

```bash
npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name scan_for_secrets \
  --tool-arg text='aws_access_key_id = AKIAIOSFODNN7EXAMPLE'
```

(That's [AWS's own publicly documented example key](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) -- not a real credential.)

## License

MIT — see [LICENSE](LICENSE).