gitleaks-mcp

An MCP server that lets an AI agent scan code, staged changes and text snippets for hardcoded secrets using gitleaks.

Secrets never reach the model. Every scan runs with --redact, and the Match/Secret fields are dropped before results are returned. The agent only sees rule, file, line, commit and fingerprint.

Status of the engine: gitleaks is feature-complete and in security-patch-only mode; its author is now building Betterleaks. The scanner sits behind a small Engine interface (src/gitleaks.ts) so a Betterleaks backend can be added once v2 is stable without changing the tool contract.

Tools

All tools are read-only and take max_findings (default 50); the total count is always reported.

Also provided: resource gitleaks://about (engine version and guarantees) and prompt pre-push-check.

Related MCP server: secret-scanner

Example

Ask your agent "scan this snippet for secrets" (or call scan_text). The token is reported by rule and line, never by value:

{
  "summary": "1 potential secret(s) found. Values are redacted.",
  "findingsCount": 1,
  "truncated": false,
  "findings": [
    {
      "rule": "github-pat",
      "description": "Uncovered a GitHub Personal Access Token, ...",
      "file": "",
      "startLine": 1,
      "endLine": 1,
      "fingerprint": ":github-pat:1"
    }
  ]
}

Typical prompts: "scan my staged changes before I commit", "check the commits I'm about to push", "does this config file contain secrets?"

Requirements

• Node >= 20

• gitleaks on your PATH (brew install gitleaks), or set GITLEAKS_BIN

Use it

git clone https://github.com/matiasburni/gitleaks-mcp && cd gitleaks-mcp
npm install && npm run build
claude mcp add gitleaks -- node "$(pwd)/dist/src/index.js"

Then ask: "scan my staged changes for secrets" or run the pre-push-check prompt.

Try it interactively with the MCP Inspector: npm run inspect.

How it works (MCP in 60 seconds)

• Transport: stdio. The client launches node dist/src/index.js and exchanges JSON-RPC over stdin/stdout, so the server never writes logs to stdout (only stderr).

• Tools are actions the model calls, declared with a zod input schema and readOnlyHint annotations (src/server.ts).

• Resources are read-only data the client can attach; prompts are reusable templates the user invokes.

• Safety: no shell (execFile with an args array), redaction forced on, secret fields dropped, temp report deleted after each scan.

Develop

npm test   # builds, then runs MCP-client end-to-end tests against real gitleaks

Test secrets are assembled at runtime so no secret-shaped literal is committed.

Security

See SECURITY.md for the threat model, hardening and known limits (notably: only scan repositories you trust).

License

MIT - see LICENSE. Permissive on purpose, so you can reuse, fork and learn from it.