mcp-scan

Security scanner for MCP server configurations.

Why this exists

MCP servers run with full filesystem and network access. Most users install them without auditing what they are actually running. mcp-scan scans your configurations automatically and surfaces what needs attention.

Quick start

npx mcp-scan

$ npx mcp-scan

  ┌ Claude Desktop › filesystem
  │ /Users/rodolf/Library/Application Support/Claude/claude_desktop_config.json
  │
  │   HIGH       exposed-secret
  │            Environment variable GITHUB_TOKEN contains a hardcoded secret.
  │            Move the value to a .env file and reference it as ${GITHUB_TOKEN}.
  │
  └────────────────────────────────────────────────

  ✓ Claude Desktop › github         0 issues
  ✓ Claude Desktop › slack          0 issues

  ────────────────────────────────────────────────
   Scanned 3 servers across 1 client in 45ms
    0 critical    1 high    0 medium    0 low
  ────────────────────────────────────────────────

What gets scanned

Windows paths are automatically detected using %APPDATA% and %USERPROFILE%.

Scanners

Severity levels

CLI reference

Output formats

• CLI table: Default color-coded output for terminal use.
• JSON: Use --json for machine-readable output.
• SARIF: Use --sarif results.sarif to import into GitHub Security tab.
• HTML report: Use --html report.html for a self-contained visual report.
• SBOM: Use --sbom sbom.json for CycloneDX v1.5 Software Bill of Materials.

CI/CD integration

GitHub Action example

name: MCP Security Scan
on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: rodolfboctor/mcp-scan@v1
        with:
          severity: high
          sarif-output: results.sarif
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

Library usage

import { runScan } from 'mcp-scan';

const report = await runScan({
  severity: 'high',
  offline: true
});

console.log(`Found ${report.totalFindings} issues.`);

Integrations

• ugig.net: MCP marketplace integration. Run mcp-scan submit --ugig-key YOUR_KEY.
• GitHub Security: Upload SARIF reports to see findings in your repository security tab.
• Slack: Send alerts to your team using --slack-webhook <url>.
• Custom webhooks: Integrate with any system using --webhook <url>.

Troubleshooting

• Rate limits: If you see GitHub API errors, set GITHUB_TOKEN in your environment.
• Config not detected: Use mcp-scan --config path/to/config.json to scan a specific file.
• Node version: Ensure you are using Node.js 18 or higher.

Architecture

Contributing

See CONTRIBUTING.md for development setup and contribution guidelines.

License

MIT. See LICENSE for details.