secscan-mcp

A portable MCP server for security scanning — works with any AI coding assistant that supports the Model Context Protocol: Cursor, VS Code, Claude Desktop, Windsurf, Zed, Continue, and more.

Scan codebases for hardcoded secrets, SAST issues, vulnerable dependencies, and IaC misconfigurations — one install, one normalized report format.

The built-in custom scanner works with no extra tools. Install optional CLIs for broader coverage (below).

Quick start

Requires Python 3.11+. If pip install secscan-mcp says "No matching distribution found", your default python3 is likely too old — use python3.11 -m pip install secscan-mcp or install Python 3.11+ first.

1. Install from PyPI:

pip install secscan-mcp
# or explicitly:
python3.11 -m pip install secscan-mcp

Or run without installing (requires uv):

uvx secscan-mcp

For MCP config with uvx, use "command": "uvx" and "args": ["secscan-mcp"] — see setup guide.

git clone https://github.com/openjkai/secscan_mcp.git
cd secscan_mcp && pip install .

2. Add to your IDE — pick your client:

Minimal config (works in Cursor, Claude Desktop, Windsurf):

{
  "mcpServers": {
    "secscan": {
      "command": "uvx",
      "args": ["secscan-mcp"]
    }
  }
}

If you installed with pip install secscan-mcp, you can use "command": "secscan-mcp" instead.

3. Verify — ask your agent: "Call list_available_scanners and scan_secrets on this project."

MCP tools

Most scan tools accept path (directory to scan) and optional severity_threshold (critical, high, medium, low, info).

scan_secrets also accepts include_git_history (boolean). When true, scans past git commits for secrets removed from the working tree but still present in history — no extra tools required beyond git. scan_all accepts include_git_history too.

Suppressing false positives

Silence known-good findings without changing scanner behavior. Both mechanisms apply to every engine, and each report includes a suppressed count so nothing is hidden silently.

.secscanignore at the project root — gitignore-style path globs:

# ignore vendored code and test fixtures
vendor/
tests/fixtures/
*.min.js

Inline # nosecscan on the offending source line — suppress all rules there, or scope to specific rule IDs:

API_TOKEN = get_token()          # real code, no marker
LEGACY_KEY = "AKIA..."           # nosecscan
DEMO_JWT = "eyJ..."              # nosecscan: hardcoded-jwt

Optional scanners

Install any of these to extend coverage. Missing CLIs are skipped — the server still runs.

After installing, run list_available_scanners again to confirm.

Example prompts

• "Call list_available_scanners and tell me what's installed."
• "Run scan_secrets with include_git_history on this repo — check if any secrets were ever committed."
• "Run scan_all with severity_threshold high and summarize the findings."
• "Explain the rule internal-api-key."
• "Add a .secscanignore for the tests/fixtures directory and re-run the scan."

Configuration

Environment variables (optional):

Pass via MCP config env block — see setup guide.

Development

make install-dev   # editable install + dev tools
make check         # lint + typecheck + test

See docs/CONTRIBUTING.md and PLAN.md.

License

MIT