npm package: @sigmabytes-official/mcpguard
Description: Offline-first security auditor for MCP (Model Context Protocol) configurations
Author: SigmaLab
Latest version: 0.1.0

# mcpguard

Offline-first security auditor for MCP (Model Context Protocol) configurations.

Scans your AI tool configs (Claude Desktop, Claude Code, Cursor, VS Code, Windsurf) for hardcoded secrets, overpermissions, supply chain vulnerabilities, and dangerous server combinations — before anything runs.

## Quick Start

```bash
npx mcpguard
```

That's it. Zero config, zero dependencies to install.

## What It Detects

- **Hardcoded secrets** — API keys, tokens, passwords, database URLs (21+ patterns including AWS, GitHub, Anthropic, OpenAI, Stripe, Slack)
- **Overpermissions** — Root filesystem access, shell execution, unrestricted network/database access
- **Command injection vectors** — Shell metacharacters, command substitution in server arguments
- **Transport security** — HTTP without TLS, missing authentication on remote servers
- **Supply chain vulnerabilities** — Known CVEs in MCP packages (e.g., CVE-2025-6514 in mcp-remote), OSV.dev lookup
- **Blast radius analysis** — Dangerous server combinations (filesystem + shell = full system compromise)
- **Config validation** — Missing args, empty credentials, URL/transport mismatches
- **OWASP ASI mapping** — Every finding tagged to OWASP Agentic Security Top 10

## Supported Clients

| Client | Config Locations |
|--------|-----------------|
| Claude Desktop | System app data directory |
| Claude Code | `.mcp.json` (project), `~/.claude.json` (user) |
| Cursor | `.cursor/mcp.json` (project), `~/.cursor/mcp.json` (global) |
| VS Code | `.vscode/mcp.json` (workspace), user settings |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |

## Usage

```bash
# Scan all detected configs
npx mcpguard

# Scan specific config file
npx mcpguard scan --config ./my-mcp-config.json

# JSON output
npx mcpguard scan --format json

# HTML report
npx mcpguard scan --format html --output report.html

# SARIF for GitHub Advanced Security
npx mcpguard scan --format sarif > results.sarif

# CI/CD: fail on high severity or above
npx mcpguard scan --fail-on high --quiet

# Include supply chain CVE checks (requires network)
npx mcpguard scan --supply-chain

# Scan only specific clients
npx mcpguard scan --clients claude-desktop cursor
```

## Auto-Fix

mcpguard can automatically extract hardcoded secrets from your configs and move them to environment variables.

```bash
# Preview proposed fixes (dry run)
npx mcpguard scan --fix

# Apply fixes
npx mcpguard scan --fix --apply
```

When applied, `--fix --apply` will:
1. Remove hardcoded secrets from your MCP config files
2. Write extracted values to `.env.mcpguard` in your working directory
3. Print instructions for setting up environment variables

## Ignoring Findings

Every finding includes a fingerprint ID (e.g., `SEC-001:github:env.GITHUB_TOKEN`). Use these to suppress known-safe findings.

```bash
# Suppress a specific finding
npx mcpguard ignore "SEC-001:github:env.GITHUB_TOKEN" --reason "Uses runtime env var"

# Show suppressed findings in output
npx mcpguard scan --show-ignored
```

This creates a `.mcpguardignore` file in your working directory. You can also create one manually:

```json
{
  "ignore": [
    { "rule": "overpermission-filesystem", "server": "filesystem-scoped", "reason": "Scoped to project dir" },
    { "fingerprint": "SEC-001:github:env.GITHUB_TOKEN", "reason": "Runtime env var" }
  ]
}
```

**Ignore rules support matching by:**
- `fingerprint` — Exact finding ID (most precise)
- `rule` — Rule name (e.g., `hardcoded-secret`, `overpermission-shell`)
- `server` — Server name from config
- `client` — Client name (e.g., `claude-desktop`, `cursor`)

Multiple fields can be combined for precise matching.

## CI/CD Integration

### GitHub Actions

```yaml
name: MCP Security Audit
on: [push, pull_request]
jobs:
  mcp-audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Scan MCP configurations
        run: npx mcpguard scan --fail-on high --format sarif --output mcp.sarif
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: mcp.sarif
```

### Exit Codes

| Code | Meaning |
|------|---------|
| `0` | Scan complete, no findings above threshold |
| `1` | Findings found at or above `--fail-on` severity |
| `2` | Error (invalid args, config parse failure, etc.) |

## Output Formats

| Format | Flag | Use Case |
|--------|------|----------|
| Terminal | `--format terminal` (default) | Human-readable with colors |
| JSON | `--format json` | Machine-readable, CI/CD pipelines |
| SARIF | `--format sarif` | GitHub Advanced Security |
| HTML | `--format html` | Shareable standalone reports |

## CLI Reference

### `mcpguard scan` (default command)

| Flag | Description |
|------|-------------|
| `-c, --config <paths...>` | Additional config file paths to scan |
| `-f, --format <format>` | Output format: `terminal`, `json`, `sarif`, `html` |
| `-o, --output <path>` | Write report to file instead of stdout |
| `--fail-on <severity>` | Exit code 1 if findings at this severity or above |
| `--clients <clients...>` | Only scan specific clients |
| `--supply-chain` | Enable supply chain CVE checks via OSV.dev |
| `--show-ignored` | Show findings suppressed by `.mcpguardignore` |
| `--fix` | Show proposed auto-fixes (dry run) |
| `--fix --apply` | Apply auto-fixes |
| `-q, --quiet` | Minimal output (findings only, no header/summary) |

### `mcpguard ignore <fingerprint>`

| Flag | Description |
|------|-------------|
| `-r, --reason <reason>` | Reason for ignoring this finding |

## How It Works

1. **Discovery** — Auto-detects MCP config files across all supported AI clients on macOS, Windows, and Linux
2. **Analysis** — Runs 7 analyzers in parallel: secrets, permissions, command injection, transport security, supply chain, blast radius, schema validation
3. **Baseline** — Filters out findings suppressed by `.mcpguardignore`
4. **Scoring** — Calculates per-finding severity scores and a machine-wide risk score (0-100)
5. **Reporting** — Outputs findings grouped by server with OWASP ASI mapping and actionable remediation

## Why mcpguard?

| | mcpguard | mcp-scan (Snyk) | Proximity |
|---|---------|-----------------|-----------|
| Offline-first | Yes | No (needs API) | No (needs LLM) |
| Secrets scanning | 21+ patterns | No | No |
| Auto-fix secrets | Yes (`--fix`) | No | No |
| Baseline/ignore | Yes (`.mcpguardignore`) | No | No |
| Multi-client discovery | 5 clients | 4 clients | Single server |
| Cross-client blast radius | Yes | No | No |
| OWASP ASI mapping | Yes | No | No |
| SARIF output | Yes | No | No |
| Supply chain CVE check | Yes (OSV.dev) | No | No |
| Config validation | Yes | No | No |
| Install friction | `npx mcpguard` | `pipx run` | Clone + install |

**Positioning**: mcp-scan analyzes *running* servers at runtime. mcpguard audits *configurations before anything runs*. They're complementary.

## License

MIT