Skip to content
Back to search

mcp-audit

See what your AI agents can access. Scan MCP configs for exposed secrets, shadow APIs, and AI models. Generate AI-BOMs for compliance.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/apisec-inc--mcp-audit/badge.svg)](/listings/apisec-inc--mcp-audit)

HTML

<a href="/listings/apisec-inc--mcp-audit"><img src="/api/listings/apisec-inc--mcp-audit/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# Install
pip install -e .

# Scan your machine
mcp-audit scan

# Or try the web app (no install)
# https://apisec-inc.github.io/mcp-audit/?demo=true

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 377 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # MCP Audit
  2. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  3. [![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
  4. [![GitHub release](https://img.shields.io/github/v/release/apisec-inc/mcp-audit)](https://github.com/apisec-inc/mcp-audit/releases)
  5. **See what your AI agents can access - before they go live.**
  6. **Web App**
  7. ![MCP Audit Web App](https://apisec-inc.github.io/mcp-audit/screenshot.png)
  8. **CLI**
  9. ![MCP Audit CLI](https://apisec-inc.github.io/mcp-audit/Screenshot2.png)
  10. ## Quick Start
  11. ```bash
  12. # Install
  13. pip install -e .
  14. # Scan your machine
  15. mcp-audit scan
  16. # Or try the web app (no install)
  17. # https://apisec-inc.github.io/mcp-audit/?demo=true
  18. ```
  19. ## What It Does
  20. MCP Audit scans your AI development tools (Claude Desktop, Cursor, VS Code) and reveals:
  21. - **Secrets** - Exposed API keys, tokens, database passwords
  22. - **APIs** - Every endpoint your AI agents connect to
  23. - **AI Models** - Which LLMs are configured (GPT-4, Claude, Llama)
  24. - **Risk Flags** - Shell access, filesystem access, unverified sources
  25. ```
  26. ⚠️ 2 SECRET(S) DETECTED - IMMEDIATE ACTION REQUIRED
  27. [CRITICAL] GitHub Personal Access Token
  28. Location: github-tools → env.GITHUB_TOKEN
  29. Remediation: https://github.com/settings/tokens → Delete → Recreate
  30. [HIGH] Database Connection String
  31. Location: postgres-mcp → env.DATABASE_URL
  32. Remediation: Rotate credentials, use secrets manager
  33. ```
  34. ## Source-level Scanning (new in v1.1)
  35. `mcp-audit scan` inventories MCP server **configurations**. The new `mcp-audit source-scan` command goes one level deeper — it reads the MCP server's own **source code** and flags code-level vulnerabilities the server author may have introduced.
  36. Today it catches the **"Prompt In, Shell Out"** attack chain: an MCP server that pipes an LLM-controlled tool argument into a shell-spawning API (`child_process.exec`, `util.promisify(exec)`, `subprocess.run(shell=True)`, `os.system`, `os.popen`) without sanitization. An attacker controlling the LLM input can inject shell metacharacters and execute arbitrary code on the host running the MCP server.
  37. ```bash
  38. $ mcp-audit source-scan ./packages/my-mcp-server
  39. MCP source-scan: packages/my-mcp-server
  40. 1 critical · 0 high · 1 finding(s) total
  41. Severity Conf File:Line API Snippet
  42. CRITICAL high server.js:19 util.promisify(child_process.exec) ... const { stdout } = await execAsync(
  43. ```
  44. Outputs:
  45. - `--format table` (default, human-readable)
  46. - `--format json` (CI integrations, jq pipelines)
  47. - `--format sarif` (upload to GitHub code-scanning / GitLab / similar)
  48. Gate merges on critical findings:
  49. ```bash
  50. mcp-audit source-scan ./my-mcp --exit-code
  51. ```
  52. The scanner is intentionally narrow — it only opens files that look like MCP server source (imports an MCP SDK). It won't try to find shell-injection bugs in random Node / Python code; that's not the job.
  53. After running `mcp-audit scan`, you'll see a nudge in the summary suggesting `source-scan` against any in-house or unverified servers it discovers.
  54. ## What It Finds (and Doesn't Find)
  55. ### What It Finds
  56. | Scan Type | Finds |
  57. |-----------|-------|
  58. | **GitHub Scan** | MCP configs committed to repositories (`mcp.json`, `.mcp/`, `claude_desktop_config.json`, etc.) |
  59. | **Local Scan** | MCP configs on your machine (Claude Desktop, Cursor, VS Code, Windsurf, Zed) |
  60. | **Source Scan** (v1.1) | Code-level vulnerabilities in MCP server source (JS/TS/Python): shell-injection sinks (`child_process.exec`, `util.promisify(exec)`, `subprocess.run(shell=True)`, `os.system`, `os.popen`) called with interpolated tool arguments |
  61. ### What It Won't Find
  62. | Blind Spot | Why |
  63. |------------|-----|
  64. | **Secrets in environment variables at runtime** | We scan config files, not running processes |
  65. | **Configs pulled from secrets managers** | Vault, AWS Secrets Manager, etc. are not scanned |
  66. | **Dynamically generated configs** | Configs created at runtime aren't in files |
  67. | **MCPs installed but not configured** | No config file = nothing to scan |
  68. | **Private repos you don't have access to** | GitHub scan is limited by your PAT scope |
  69. | **Encrypted or obfuscated secrets** | Pattern matching won't catch encoded values |
  70. | **Non-standard config locations** | Custom paths outside known locations |
  71. ### Important
  72. **A clean scan does not mean zero risk.**
  73. - Developers may have MCPs configured on machines you haven't scanned
  74. - Configs may exist in repos outside your GitHub org
  75. - Runtime behavior may differ from static configuration
  76. MCP Audit provides visibility, not guarantees. Use alongside runtime monitoring and security reviews.
  77. ## CI/CD Integration
  78. Fail builds on critical risks:
  79. ```yaml
  80. # .github/workflows/mcp-audit.yml
  81. name: MCP Security Audit
  82. on: [push, pull_request]
  83. jobs:
  84. audit:
  85. runs-on: ubuntu-latest
  86. steps:
  87. - uses: actions/checkout@v4
  88. - name: Install MCP Audit
  89. run: pip install mcp-audit
  90. - name: Run Security Scan
  91. run: mcp-audit scan --path . --format json -o mcp-report.json
  92. - name: Fail on Critical
  93. run: |
  94. CRITICAL=$(jq '[.mcps[] | select(.risk == "critical")] | length' mcp-report.json)
  95. if [ "$CRITICAL" -gt 0 ]; then
  96. echo "❌ Found $CRITICAL critical-risk MCPs"
  97. exit 1
  98. fi
  99. - name: Upload AI-BOM
  100. uses: actions/upload-artifact@v4
  101. with:
  102. name: ai-bom
  103. path: mcp-report.json
  104. ```
  105. ### Source-level scan in CI (v1.1)
  106. If you ship an in-house MCP server, gate merges on critical code-level findings:
  107. ```yaml
  108. # .github/workflows/mcp-source-scan.yml
  109. name: MCP Source Scan
  110. on: [pull_request]
  111. jobs:
  112. source-scan:
  113. runs-on: ubuntu-latest
  114. steps:
  115. - uses: actions/checkout@v4
  116. - run: pip install mcp-audit
  117. # Fail the PR if any critical shell-injection findings are detected.
  118. - name: Source-scan in-house MCP server
  119. run: mcp-audit source-scan ./packages/my-mcp-server --exit-code
  120. # OR: upload findings to GitHub code-scanning instead of failing.
  121. - name: Source-scan -> SARIF
  122. run: mcp-audit source-scan ./packages/my-mcp-server --format sarif --output mcp.sarif
  123. - uses: github/codeql-action/upload-sarif@v3
  124. with:
  125. sarif_file: mcp.sarif
  126. ```
  127. ## Export Formats
  128. ```bash
  129. # JSON (for CI/CD)
  130. mcp-audit scan --format json -o report.json
  131. # AI-BOM (CycloneDX 1.6)
  132. mcp-audit scan --format cyclonedx -o ai-bom.json
  133. # SARIF (GitHub Security integration)
  134. mcp-audit scan --format sarif -o results.sarif
  135. # CSV / Markdown
  136. mcp-audit scan --format csv -o report.csv
  137. mcp-audit scan --format markdown -o report.md
  138. # PDF Report via Email
  139. mcp-audit scan --email security@company.com
  140. ```
  141. ---
  142. ## Key Features
  143. | Feature | Description |
  144. |---------|-------------|
  145. | **MCP Discovery** | Find MCPs in Claude Desktop, Cursor, VS Code, Windsurf, Zed |
  146. | **Secrets Detection** | 25+ secret patterns with provider-specific remediation |
  147. | **API Inventory** | Database, REST, SSE, SaaS, Cloud endpoints |
  148. | **AI Model Detection** | OpenAI, Anthropic, Google, Meta, Mistral, Ollama |
  149. | **OWASP LLM Top 10** | Maps findings to OWASP LLM Top 10 (2025) framework |
  150. | **AI-BOM Export** | CycloneDX 1.6 for supply chain compliance |
  151. | **SARIF Output** | GitHub Security integration with OWASP tags |
  152. | **Registry** | 50+ known MCPs with risk classifications |
  153. ## Two Ways to Use
  154. | | **Web App** | **CLI Tool** |
  155. |---|-------------|--------------|
  156. | **Scans** | GitHub repositories | Local machine |
  157. | **Install** | None (browser) | Python 3.9+ |
  158. | **Best for** | Org-wide visibility | Deep local analysis |
  159. | **Privacy** | Token stays in browser | 100% local |
  160. **Web App:** [https://apisec-inc.github.io/mcp-audit/](https://apisec-inc.github.io/mcp-audit/)
  161. ---
  162. ## CLI Reference
  163. ### Scan Commands
  164. ```bash
  165. mcp-audit scan # Full inventory scan
  166. mcp-audit scan --secrets-only # Only secrets
  167. mcp-audit scan --apis-only # Only API endpoints
  168. mcp-audit scan --models-only # Only AI models
  169. mcp-audit scan --verbose # Detailed output
  170. mcp-audit scan --path ./project # Specific directory
  171. ```
  172. ### Source-level Scan Commands (new in v1.1)
  173. `source-scan` is a separate command from `scan`. `scan` inventories MCP configurations; `source-scan` reads MCP server source code and flags code-level vulnerabilities. See [docs/SOURCE_SCAN.md](docs/SOURCE_SCAN.md) for the full guide.
  174. ```bash
  175. mcp-audit source-scan ./my-mcp # Table output (default)
  176. mcp-audit source-scan ./my-mcp --format json # JSON for jq pipelines
  177. mcp-audit source-scan ./my-mcp --format sarif # SARIF for code-scanning
  178. mcp-audit source-scan ./my-mcp --output mcp.sarif # Write to file
  179. mcp-audit source-scan ./my-mcp --exit-code # CI gate (non-zero on critical)
  180. mcp-audit source-scan ./my-mcp --explain # Inline remediation guidance
  181. ```
  182. ### Export Options
  183. ```bash
  184. mcp-audit scan --format json -o report.json # JSON output
  185. mcp-audit scan --format csv -o report.csv # CSV output
  186. mcp-audit scan --format markdown -o report.md # Markdown output
  187. mcp-audit scan --format cyclonedx -o ai-bom.json # CycloneDX 1.6 AI-BOM
  188. mcp-audit scan --format sarif -o results.sarif # SARIF for GitHub Security
  189. mcp-audit scan --email security@company.com # PDF report via email
  190. ```
  191. ### Registry Commands
  192. ```bash
  193. mcp-audit registry # List all known MCPs
  194. mcp-audit registry --risk critical # Filter by risk
  195. mcp-audit registry lookup "stripe" # Search registry
  196. ```
  197. ### Explain a Risk Flag
  198. ```bash
  199. mcp-audit explain shell-injection-in-source # Full remediation guidance
  200. mcp-audit explain --list # All known risk flags
  201. ```
  202. ---
  203. ## Risk Levels
  204. | Level | Meaning | Examples |
  205. |-------|---------|----------|
  206. | 🔴 **CRITICAL** | Full system access | Database admin, shell access, cloud IAM |
  207. | 🟠 **HIGH** | Write access | Filesystem write, API mutations |
  208. | 🟡 **MEDIUM** | Read + limited write | SaaS integrations, read-only DB |
  209. | 🟢 **LOW** | Read-only | Public APIs, memory storage |
  210. ## Detected Secrets
  211. | Severity | Types |
  212. |----------|-------|
  213. | 🔴 Critical | AWS Keys, GitHub PATs, Stripe Live Keys, DB Credentials |
  214. | 🟠 High | Slack Tokens, OpenAI Keys, Anthropic Keys, SendGrid |
  215. | 🟡 Medium | Webhooks, Generic API Keys |
  216. ---
  217. ## Privacy
  218. - **Web App**: GitHub token never leaves your browser
  219. - **CLI**: Runs 100% locally, no telemetry
  220. - **PDF Reports**: Only summary data sent (no secrets)
  221. ---
  222. ## Installation
  223. ### Option 1: Python (pip)
  224. ```bash
  225. # Clone and install
  226. git clone https://github.com/apisec-inc/mcp-audit.git
  227. cd mcp-audit
  228. pip install -e .
  229. # Verify
  230. mcp-audit --help
  231. ```
  232. Requires Python 3.9+
  233. ### Option 2: Docker
  234. ```bash
  235. # Build image
  236. docker build -t mcp-audit .
  237. # Scan current directory
  238. docker run -v $(pwd):/scan mcp-audit scan
  239. # Scan with JSON output
  240. docker run -v $(pwd):/scan mcp-audit scan --format json -o /scan/report.json
  241. ```
  242. ---
  243. ## Verify Download Integrity
  244. All MCP Audit releases include SHA256 checksums.
  245. ### Verify CLI Download
  246. ```bash
  247. # Download the checksum file
  248. curl -O https://github.com/apisec-inc/mcp-audit/releases/latest/download/CHECKSUMS.txt
  249. # Verify the zip file
  250. shasum -a 256 -c CHECKSUMS.txt --ignore-missing
  251. ```
  252. Expected output:
  253. ```
  254. mcp-audit-cli.zip: OK
  255. ```
  256. ### Current Release Checksum
  257. | File | SHA256 |
  258. |------|--------|
  259. | `mcp-audit-cli.zip` | `4917a451742038355265b0d9a74c0bb2b3a5ada28798ce3dd43238a8defcaa73` |
  260. Full checksums: [CHECKSUMS.txt](CHECKSUMS.txt)
  261. ---
  262. ## Documentation
  263. - **[Risk Scoring](docs/RISK_SCORING.md)** - How risk levels and flags are assigned
  264. - **[Contributing](CONTRIBUTING.md)** - Guidelines for contributors
  265. ## License
  266. MIT - see [LICENSE](LICENSE)
  267. ---
  268. Built by [APIsec](https://apisec.ai)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.