audit-mcp-cli

English | 中文

A lightweight dependency vulnerability audit tool for Node.js projects. Supports CLI and MCP Server modes, covers npm and pnpm projects, and generates structured Markdown/HTML reports with full dependency chains.

Features

• Full dependency chains — traces the complete path from your package.json to each vulnerable package
• npm + pnpm support — auto-detects package manager by lockfile
• Remote GitHub audit — audit any public or private repo without cloning
• MCP Server — integrates with AI coding assistants (Claude, Cursor, etc.)
• Markdown / HTML reports — clean, structured reports sorted by severity
• CI gate — --fail-on exit code for CI/CD pipelines
• Ignore mechanism — suppress accepted vulnerabilities with expiration dates
• Severity filtering — show only vulnerabilities above a threshold

Install

# Run directly
npx audit-mcp-cli

# Or install globally
npm install -g audit-mcp-cli

Requires Node.js >= 18.

Usage

# Audit current directory
audit-mcp-cli

# Specific project path
audit-mcp-cli --path /path/to/project

# Remote GitHub repo (branch)
audit-mcp-cli --remote github:facebook/react --ref main

# Remote GitHub repo (tag)
audit-mcp-cli --remote github:facebook/react --ref v18.2.0

# Remote GitHub repo (commit SHA)
audit-mcp-cli --remote github:facebook/react --ref abc123def

# HTML report
audit-mcp-cli --format html --output report.html

# CI: fail if high+ severity vulnerabilities found
audit-mcp-cli --fail-on high

# Severity filtering (only show high and critical)
audit-mcp-cli --severity high

CLI Options

| Option | Description | Default | |--------|-------------|---------| | --path <path> | Local project path | process.cwd() | | --remote <repo> | Remote repo: github:owner/repo or https://github.com/owner/repo | — | | --ref <ref> | Git ref (branch name / tag / commit SHA) | main | | --token <token> | GitHub personal access token (for private repos) | GITHUB_TOKEN env | | --format <fmt> | Report format: md or html | md | | --output <path> | Output file path | audit-report.md or .html | | --severity <level> | Minimum severity to display: low / moderate / high / critical | low | | --fail-on <level> | CI fail threshold — exit 1 if vulnerabilities at this level or above exist | — | | --mcp | Start as MCP Server | — | | --lang <lang> | Language: en or zh-CN | Auto-detect from system |

--fail-on exit codes

| Value | Exits 1 when | |-------|-------------| | critical | Any critical vulnerability found | | high | Any high or critical found | | moderate | Any moderate, high, or critical found | | low | Any vulnerability found | | (not set) | Always exits 0 |

MCP Server

Run as an MCP stdio server for AI assistants:

audit-mcp-cli --mcp

Claude Desktop

Basic (local projects & public repos):

{
  "mcpServers": {
    "audit-mcp-cli": {
      "command": "npx",
      "args": ["-y", "audit-mcp-cli", "--mcp"]
    }
  }
}

With GitHub token (private repos / avoid rate limits):

{
  "mcpServers": {
    "audit-mcp-cli": {
      "command": "npx",
      "args": ["-y", "audit-mcp-cli", "--mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxx"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json:

Basic (local projects & public repos):

{
  "mcpServers": {
    "audit-mcp-cli": {
      "command": "npx",
      "args": ["-y", "audit-mcp-cli", "--mcp"]
    }
  }
}

With GitHub token (private repos / avoid rate limits):

{
  "mcpServers": {
    "audit-mcp-cli": {
      "command": "npx",
      "args": ["-y", "audit-mcp-cli", "--mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxx"
      }
    }
  }
}

Tool: audit_dependencies

The MCP server exposes one tool that supports both local and remote auditing:

| Parameter | Description | |-----------|-------------| | projectPath | Local project path | | remoteRepo | Remote repo: github:owner/repo | | ref | Git ref (branch / tag / SHA) | | token | GitHub token (for private repos, or use GITHUB_TOKEN env) | | format | md or html | | severity | Minimum severity filter | | outputPath | Custom output file path |

Returns: report file path + structured vulnerability details (CVSS, dependency chains, fix suggestions).

Token is optional. Local project auditing never requires a token. Remote public repos work without a token (60 requests/hour). Only private repos require a GitHub token.

Ignore Mechanism

Create .audit-mcp-cli-ignore.json in your project root to suppress accepted vulnerabilities:

{
  "ignore": [
    {
      "packageName": "minimist",
      "advisorySource": 1179,
      "reason": "Accepted risk, limited impact in our usage",
      "expiresAt": "2025-12-31T00:00:00Z"
    }
  ]
}

• packageName — match all advisories for this package, or combine with advisorySource for exact match
• expiresAt — optional, ignore auto-expires after this date
• Ignored vulnerabilities are shown in a separate section of the report and excluded from --fail-on checks

CI Integration

# GitHub Actions example
- name: Security Audit
  run: npx audit-mcp-cli --fail-on high

# Generic CI
npx audit-mcp-cli --fail-on high && echo "pass" || echo "fail"

License

MIT