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

`--fail-on` exit codes

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:

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