cleanlib-mcp-server

CleanLibrary MCP (Model Context Protocol) server — gives AI agents (Claude Code, Claude Desktop, Cursor, etc.) read access to CleanLibrary's library-verdict + vulnerability-intelligence APIs. Your agent can call cleanlib_fetch_verdict to ask "should we use lodash@4.17.20?" and get a structured response with verdict tier (ALLOW / WARN / DENY), CVE references, fix recommendations, and KMS-signed attestation.

Install

pip install cleanlib-mcp-server

Latest: 0.5.x on PyPI. 14 tools covering verdict / advisories / exploitability / EPSS / KEV / remediation / Vector / bulk operations.

Configure

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "cleanlib": {
      "command": "cleanlib-mcp-server",
      "env": {
        "CLEANLIB_ENDPOINT": "https://cleanapp.clnstrt.dev",
        "CLEANLIB_API_KEY": "clk_YOUR_BEARER_HERE",
        "CLEANLIB_ENRICH_BEARER": "clk_YOUR_BEARER_HERE"
      }
    }
  }
}

Restart Claude Desktop. The 14 tools should appear in the tool picker.

Claude Code

In your .claude/settings.json or via the claude mcp add command:

claude mcp add cleanlib \
  --command cleanlib-mcp-server \
  --env CLEANLIB_ENDPOINT=https://cleanapp.clnstrt.dev \
  --env CLEANLIB_API_KEY=clk_YOUR_BEARER_HERE \
  --env CLEANLIB_ENRICH_BEARER=clk_YOUR_BEARER_HERE

Cursor / other MCP clients

The server speaks standard MCP over stdio. The same command + env pattern applies — consult your client's MCP server configuration docs for the exact file location.

Bearer provisioning

CleanLibrary uses two bearer scopes:

For most customers these are the same bearer with both scopes; your design-partner / pilot agreement will spell out the tier.

Tier shape

On rate-limit hit: HTTP 429 + Retry-After: <seconds> header. Honor it.

Provisioning flow

1. Request bearer via your CleanLibrary design-partner / pilot contact at cto@cleanstart.com
2. Receive a token of the form clk_<random>_<tier> (e.g. clk_abc...xyz_001 for standard-tier-pilot)
3. Store in your local config file (above) or a secret manager:
   • macOS: Keychain (recommended) or ~/.config/cleanlib/bearer
   • Linux: ~/.config/cleanlib/bearer or your customer-side secret store
   • Cloud/CI: GitHub Actions Secret / GitLab CI variable / AWS SSM / GCP Secret Manager
4. Never commit bearer tokens to a repository. Keep them in environment variables or secret managers.

Tool reference

14 tools post v0.5.0:

Verify it works

In Claude Code or Claude Desktop, ask:

"What's the CleanLibrary verdict for npm/lodash/4.17.20?"

The agent should invoke cleanlib_fetch_verdict and return something like:

The verdict is DENY (verdict source: VECTOR_VERDICT, severity HIGH, composite score 81). 5 CVEs affect this version. Top: CVE-2026-4800 (HIGH, CVSS 8.1, fixed in 4.18.0). Recommended action: upgrade to 4.17.21+ to address all 5 CVEs, or to 4.18.0+ for the cleanest path.

If you get AUTH_ERROR or bearer required: double-check the env block in your config file.

If every package returns ALLOW_BY_ABSENCE: your CLEANLIB_ENRICH_BEARER may be missing or scoped wrong. Run cleanlib_health_check — it returns the backend's honest state.

Diagnose bearer configuration

If verdict tools work but enrichment tools (advisories, exploitability, epss, kev, cve_enrich, remediation, bulk variants) return PermissionError or silently produce empty results, the two bearer pools are non-interchangeable and one of them is misconfigured. Run the built-in diagnostic from the same shell that launches your MCP client (so the same env vars are visible):

cleanlib-mcp-server --test-bearers

It probes both pools end-to-end (App /v1/customer/verdicts/... + enrich /api/v1/advisories/...) with whatever CLEANLIB_API_KEY and CLEANLIB_ENRICH_BEARER your environment carries, and reports [OK] / [FAIL] / [SKIP] per pool. Exit code is non-zero if any required bearer is missing or rejected — wire it into your onboarding smoke-check.

Sample agent prompts

These work across Claude Code / Claude Desktop:

• "Check requirements.txt packages against CleanLibrary and flag any DENY."
• "What CVEs affect npm/express/4.17.1?"
• "Should I upgrade lodash from 4.17.20? Show me the upgrade journey."
• "Cross-check python-cryptography/3.4.7 for KEV and EPSS data."

What ships today

• ✅ Rate-limit enforcement — per-minute quotas (above) with HTTP 429 + Retry-After header
• ✅ App-layer caching — vulnerability cross-reference TTL cache (5-min default) with as_of honesty (cache-hit responses carry the original substrate-fetch time, not cache-read time)
• ✅ Observability foundation — Cloud Monitoring custom-metrics + availability.degraded_stale honesty signal on verdict envelope
• ✅ KMS-signed attestation — every verdict carries an externally-verifiable ECDSA-P256 signature anchored at cleanlibrary-prod KMS

What's NOT shipped yet (honest gaps)

• Per-route SLA differentiation — single Cloud Run service handles all routes today; per-route quotas land cycle-16
• Full availability block population — schema present + degraded_stale live; kev / epss / exploitation_fusion sub-fields land cycle-16
• Multi-region — single us-central1; EU sovereign deployment is a BD-trigger
• Self-hosted enrich-api offering — hosted-only today; air-gap customers contact cto@cleanstart.com

Run

cleanlib-mcp-server   # stdio transport (per MCP spec)

Backend modes

• Connected — when CLEANLIB_ENDPOINT + CLEANLIB_API_KEY are set, the server queries your CleanLibrary deployment for live verdicts.
• Local fixtures — when no endpoint is configured (or the configured endpoint is unreachable), the server returns bundled demo fixtures so MCP clients always receive useful output during local development.

Troubleshooting

Development

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
ruff check src tests
pytest -v

More docs

Beyond this 5-minute quickstart, the docs/ directory carries the long-form onboarding material:

• docs/customer-onboarding.md — end-to-end provisioning → install → verify → production-hardening walkthrough for design-partners and new customers (bearer storage matrix per environment, onboarding SLA).
• docs/first-verdict-walkthrough.md — scripted per-tool tour (all 14 tools) with concrete agent prompts and expected response shapes; includes a paste-ready one-shot script that exercises the full non-deprecated surface.
• docs/troubleshooting.md — symptom-first decision tree isolating App-plane vs enrich-plane vs client-side failures; covers stale-version banner (v0.5.0 → v0.5.4 fork-drift class), rate-limit posture, and honest-absence semantics.

Feedback / contact

• Issues / questions: cto@cleanstart.com
• Source: https://bitbucket.org/triamsec/cleanlib-mcp-server

License

Proprietary. See LICENSE for terms. © 2026 CleanStart Inc.