Skip to main content
Glama
README.md
# mcp-secrets-guard

An [MCP](https://modelcontextprotocol.io) server that lets AI assistants check your project for exposed secrets **without the secret values ever entering the model's context**.

Instead of letting an assistant `cat .env` (and leak your keys into a chat log), the assistant calls a tool. The tool reads the file locally and returns only a sanitized report:

```
.env: Found 3 potential secrets: 1 AWS access key ID, 1 Stripe live secret key, 1 High-entropy secret value.
  - line 2: AWS access key ID [high] (variable AWS_ACCESS_KEY_ID)
  - line 3: Stripe live secret key [high] (variable STRIPE_SECRET_KEY)
  - line 4: High-entropy secret value [medium] (variable SESSION_SECRET)
  ! This env file does not appear to be covered by .gitignore.
Secret values are never included in this report.
```

No value, prefix, suffix or masked fragment is ever returned. The test suite asserts this against the real MCP protocol.

## Install

**Claude Desktop** — add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "secrets-guard": {
      "command": "npx",
      "args": ["-y", "mcp-secrets-guard"],
      "env": { "MCP_SECRETS_GUARD_ROOT": "/absolute/path/to/your/project" }
    }
  }
}
```

**Claude Code:**

```bash
claude mcp add secrets-guard -- npx -y mcp-secrets-guard
```

(Claude Code launches servers in your project directory, so the root defaults to it.)

## Tools

| Tool | What it does |
| --- | --- |
| `check_env_for_secrets` | Scans one env file (default `.env`). Reports line numbers, secret types, variable names, and whether the file looks covered by `.gitignore`. |
| `scan_project_for_secrets` | Recursively scans the project (skips `node_modules`, `.git`, build output, lockfiles, binaries, files over 1 MB) for hard-coded secrets. |

## What it detects

Anthropic, OpenAI, AWS access key IDs, Stripe (live/test/webhook), GitHub (classic and fine-grained), Slack tokens and webhooks, Google API keys, SendGrid, Twilio, npm tokens, private key blocks, JWTs, passwords in connection strings (`postgres://user:pass@host`), plus a generic entropy check for values under names like `*_SECRET`, `*_TOKEN`, `*PASSWORD*`, `*API_KEY*`. Placeholders (`your_key_here`, `${VAR}`, `changeme`, `<...>`) are ignored.

This is a fast heuristic scanner, not a replacement for tools like gitleaks or trufflehog in CI. Expect some false negatives (and the occasional false positive).

## Safety model

- **Read-only.** Nothing is written, deleted or sent anywhere. No network access.
- **Root-confined.** Paths are resolved (including symlinks) and must stay inside the project root (`MCP_SECRETS_GUARD_ROOT`, default: current directory). `../` and symlink escapes are refused.
- **Errors never echo file contents.**
- **One dependency:** the official `@modelcontextprotocol/sdk`.

A note on trust: this protects the secret *values* from the model. It cannot stop an assistant that also has a general file-read tool from reading `.env` anyway. Pair it with your client's permission rules (e.g. deny reads of `.env*`) so the guarded tool is the only path.

## CLI

```bash
npx mcp-secrets-guard --scan          # scan the project, exit code 1 if anything is found
npx mcp-secrets-guard --scan .env
```

Handy as a pre-commit hook or CI step.

## Develop

```bash
npm install
npm test
```

## License

MIT

TDQS

A3.9/5.0

Scored across 2 tools

Disambiguation4/5

The two tools are differentiated by scope: check_env_for_secrets targets a single env file while scan_project_for_secrets recursively scans the whole project. However, the recursive scan likely also covers env files, creating partial overlap that an agent must reason about from the descriptions rather than from distinct purposes.

Naming Consistency5/5

Both tools follow a clear, consistent verb_noun_for_secrets pattern (check_env_for_secrets, scan_project_for_secrets) with matching suffix semantics. The verb difference (check vs scan) also maps sensibly to single-file vs recursive scope.

Tool Count3/5

Two tools is thin for a scanner/guard server; it sits at the borderline where the surface feels minimal. The split is defensible (file-level vs project-level), but there is little room for configuration, baselines, or reporting tools.

Completeness3/5

Detection coverage is reasonable for the domain, but the lifecycle is incomplete: there is no way to configure ignore rules/custom patterns, manage an allowlist or baseline, export reports, or receive remediation guidance. These are notable gaps for a 'guard' toolset, though agents can still perform the core detection workflow.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues