{
  "markdown": "<!-- mcp-name: io.github.H129hj/checkmcp -->\n\n# CheckMCP\n\n[![PyPI](https://img.shields.io/pypi/v/audit-mcp)](https://pypi.org/project/audit-mcp/) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) [![GitHub Action](https://img.shields.io/badge/CI-GitHub%20Action-2088FF?logo=githubactions&logoColor=white)](action.yml) [![Web audit](https://img.shields.io/badge/web-checkmcp.dev-blue)](https://checkmcp.dev)\n\n**Vendor-neutral quality / security / context-cost audit & score for any MCP server.**\nOne `uvx`/`pipx` command → an **MCP Score /100** + **causal opportunities** (why the score), Lighthouse-style.\n\n> Installed from PyPI as **`audit-mcp`** (the name `checkmcp` was already taken); the command is `audit-mcp`. Brand, site and repo remain **CheckMCP** / checkmcp.dev.\n\n```bash\nuvx audit-mcp https://mcp.deepwiki.com/mcp\n# or\npipx run audit-mcp https://mcp.context7.com/mcp --json\naudit-mcp https://my-mcp.example.com/mcp --token \"$TOKEN\"\n```\n\n## Use it as an MCP server\n\n`audit-mcp mcp` turns the auditor itself into an MCP server (stdio) exposing one tool,\n`audit_mcp_server` — so your agent can answer *\"is this MCP server safe?\"* mid-conversation.\n\n```bash\n# Claude Code\nclaude mcp add audit-mcp -- uvx audit-mcp mcp\n```\n\n```json\n// Cursor (.cursor/mcp.json) / Claude Desktop (claude_desktop_config.json)\n{ \"mcpServers\": { \"audit-mcp\": { \"command\": \"uvx\", \"args\": [\"audit-mcp\", \"mcp\"] } } }\n```\n\nRegistry name: `io.github.H129hj/checkmcp` <!-- mcp-name: io.github.H129hj/checkmcp -->\n\n\nNo dependencies (stdlib only). `tiktoken` optional for exact token counts.\n\n## What it measures (7 pillars)\n- **Security** — OWASP MCP Top 10 (tool poisoning, hardcoded secrets, command injection), lethal-trifecta.\n- **Tool design** — sprawl/consolidation (percentile-calibrated on real servers: median ~7 tools, p95 ~42).\n- **Schemas / desc** — descriptions + `inputSchema`/`outputSchema` completeness.\n- **Context-cost** — tokens spent on `tools/list`, paid on every request (the #1 pain of 2026).\n- **Compliance** — protocol-version gap, annotations, JSON-RPC error conformance, OAuth discovery.\n- **Reliability** — single-shot today (not credited; continuous T3 monitoring on checkmcp.dev).\n- **Coverage** — the 3 primitives (tools **+ resources + prompts**).\n\nHard floors: secret-in-schema → cap D, failed handshake → cap F. Every penalty is attributed: `measure → mechanism → effect → Δscore`.\n\n## CLI flags\n| flag | what |\n|---|---|\n| `--json` | machine-readable report |\n| `--badge` | SVG badge + README embed snippets |\n| `--html` | standalone SEO/GEO page (JSON-LD `SoftwareApplication` + FAQ) |\n| `--repo owner/name` | add maintenance/license/provenance signal from GitHub |\n| `--token <bearer>` | audit an OAuth-protected server |\n| `--min-score N` | CI: exit 1 if MCP Score < N |\n| `--baseline file` | CI: pin tool definitions; fail on regression (rug-pull) |\n| `--gh-summary` | CI: write a Markdown summary to `$GITHUB_STEP_SUMMARY` |\n| `--deep` | runtime depth via an external scanner (mcp-scan/snyk) if present |\n| `--evals` | behavioral sandbox: actually invokes read-only tools with canary inputs to catch tool-output prompt-injection, exfiltration vectors, secret/PII leakage and context bombs (sends real traffic; CI-fails on a malicious verdict) |\n\n## GitHub Action\n\n```yaml\n# .github/workflows/mcp-audit.yml\nname: MCP audit\non: [push, pull_request]\njobs:\n  checkmcp:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: H129hj/checkmcp@v1\n        with:\n          url: https://my-mcp.example.com/mcp\n          min-score: \"70\"\n          baseline: .checkmcp-baseline.json   # commit it → fails on rug-pull\n```\n\n## Behavioral evals (`--evals`)\nStatic analysis catches *declared* danger; `--evals` catches *runtime* danger by actually invoking\nread-only tools with canary inputs and inspecting the **responses** for tool-output prompt-injection,\nexfiltration vectors and secret/PII leakage (multilingual; optional callback-canary confirms exfil).\nCI-fails on a malicious verdict.\n\n## Self-hosted security gateway\nBeyond auditing, CheckMCP ships an **in-band MCP gateway** — a proxy you put between your agent and an\nMCP server. It inspects every call, and in *active* mode **blocks/strips** tool-poisoning & exfiltration\nbefore they reach the agent. Run it in your own infra (tool traffic never leaves your network):\n\n```bash\ndocker pull ghcr.io/h129hj/checkmcp-gateway:latest   # or build from source\ndocker run -p 8080:8080 -e GATEWAY_BACKEND_URL=https://mcp.example.com/mcp \\\n  -e GATEWAY_MODE=active -e GATEWAY_SECRET=$(openssl rand -hex 16) \\\n  ghcr.io/h129hj/checkmcp-gateway:latest\n```\n\nSee **[GATEWAY.md](GATEWAY.md)** for config (passive/active, OAuth backends, policy, logs).\n\n## Hosted\nFull reports, public directory, live badges, continuous drift monitoring, a governance policy API and a\nhosted gateway at **[checkmcp.dev](https://checkmcp.dev)**.\n\n## Honest limitations\n- Percentile bands come from a growing corpus (one+ registries) — widening over time.\n- Exact tokens with `pipx install \"audit-mcp[exact-tokens]\"` (cl100k_base); otherwise chars/4 approximation.\n- Pillar weights are expert priors. `python -m checkmcp.calibrate samples.json` validates them against a labeled agent-success sample (per-pillar correlation + OLS-suggested weights + construct-validity R²) — supply real outcomes to close the loop.\n\nMIT.\n",
  "bytes": 5408,
  "sha": "bc5d895ff3822be50105061c565f6ac57c28a8b7e3a39a92bfb2eea3be932db4",
  "repo_slug": "h129hj/checkmcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_h129hj_checkmcp_d6f3dbeb/readme"
}