osidb-mcp

Python Model Context Protocol (MCP) server for OSIDB, built on osidb-bindings from PyPI. Use it from Cursor, Claude Desktop, or any MCP client over stdio. PyPI: pypi.org/project/osidb-mcp · Homebrew: vdanen/osidb-mcp · Source: github.com/vdanen/osidb-mcp.

Install

Homebrew

brew tap vdanen/osidb-mcp
brew install osidb-mcp

After the tap is installed, upgrades use brew upgrade osidb-mcp.

PyPI

Published on PyPI as osidb-mcp:

pipx install osidb-mcp
# or
pip install osidb-mcp

Print the installed package version (no OSIDB env or credentials required):

osidb-mcp --version
# or: osidb-mcp -V

Configuration (environment)

Kerberos: the process must have a valid ticket (kinit) for the OSIDB HTTP service.

Optional keys forwarded by bindings: BUGZILLA_API_KEY, JIRA_ACCESS_TOKEN, JIRA_API_EMAIL.

Cursor / Claude MCP snippet

{
  "mcpServers": {
    "osidb": {
      "command": "osidb-mcp",
      "env": {
        "OSIDB_BASE_URL": "https://your-internal-osidb",
        "OSIDB_AUTH": "kerberos",
        "OSIDB_VERIFY_SSL": "true",
        "OSIDB_MCP_ACCESS_MODE": "readonly"
      }
    }
  }
}

Tools (read-only)

All MCP tools require a working OSIDB session (env + Kerberos or basic auth). The CLI osidb-mcp --version / -V does not contact OSIDB (see Install). The table lists every registered tool, in the same order as server.py. For longer explanations, example prompts, and limitations, see TOOLS.md. If an LLM agent is calling these tools, read Using with AI agents first.

limit (and analogous list limits) are capped at 100 per request unless noted otherwise on a tool.

When to use which

• Triage / natural language style: search_flaws, get_flaw_details, get_cve_summary.

• Exact OpenAPI filters or rare query keys: flaws_list / flaws_count with extra_query (allowlisted keys only).

• Affect- or tracker-centric views: affects_list, trackers_list, or the subresource tools under a known flaw id.

Flaw identifiers (CVE vs internal uuid)

OSIDB flaws always have an internal uuid. A cve_id may be missing until one is assigned — that is normal, not “no identifier.”

• List/search responses include each flaw’s uuid in JSON. flaws_list, flaws_search, and search_flaws (structured path) also return an identifier_hint string for agents.

• flaw_get / get_flaw_details: when there is no usable CVE string, the tool adds top-level osidb_flaw_uuid (same value as flaw.uuid) so follow-up calls are obvious.

• get_flaw_details: if cve_id is empty, affects and trackers are loaded using flaw__uuid / affects__flaw__uuid automatically.

• affects_list / query_affects: use flaw_uuid / flaw_uuid_in to scope rows when there is no CVE. trackers_list: use affects_flaw_uuid / affects_flaw_uuid_in.

• flaw_comments_list, flaw_references_list, flaw_cvss_scores_list, flaw_acknowledgments_list, flaw_labels_list, flaw_package_versions_list: the flaw_id argument is the same as for flaw_get — CVE string or internal uuid. If you use include_fields on flaw_get, include uuid when you still need it downstream.

Analyst examples

• Same idea as “search CVEs”: use search_flaws with keyword, or combine cve_ids, severity / severities, date_from / date_to, and product_modules / product_components.

• Critical open flaws touching httpd: search_flaws or flaws_list with impact="CRITICAL", workflow_state_in for non-terminal states, and product_components=["httpd"] or components_in / affects_ps_component as your data model requires.

• Unowned important CVEs for a RHEL major: search_flaws with owner_isempty=true, severities=["IMPORTANT"], and product_modules / product_components set to the exact PS strings your OSIDB uses for that major (confirm in your internal docs).

• Executive rollup: get_cve_summary with optional date range and product filters; tune group_by if you only need severity or only workflow buckets.

Using with AI agents

These tools return structured JSON (sometimes large). The MCP host (Cursor, Claude Desktop, API client) chooses the LLM — this server cannot select or downgrade a model for you.

• Good default: A mid-tier model (e.g. Sonnet-class) is usually enough for reliable tool names, filters, and reading nested flaw / affect / tracker data.

• Smaller / cheaper models: Reasonable for narrow tasks (one CVE, a known tool, counts only). Tight prompts help; ambiguous multi-step triage may need more retries or a larger model.

• Largest models: Optional when the task is underspecified or you need unusually careful synthesis; for routine read-only chains they are often more than needed.

• Saving tokens: Use include_fields / exclude_fields where supported; prefer flaws_count or get_cve_summary over pulling many full list pages; keep limit modest; ask the agent to summarize instead of echoing entire tool payloads unless you are debugging.

Security

See SECURITY.md for the threat model, OWASP-oriented checklist, and access-mode behavior.

• Outputs may include embargoed content; treat transcripts and logs according to your data classification policy (especially when using hosted LLMs).

• OSIDB_MCP_ACCESS_MODE=readonly is the only supported value today — readwrite exits at startup. When mutation tools exist later, use two MCP entries (readonly vs write-capable) so writes happen only when you intend them.

• Never commit OSIDB_PASSWORD; use IDE env or secret stores.

Development

uv venv .venv && source .venv/bin/activate
uv pip install -e ".[dev]"
python -m osidb_mcp
pytest tests
pip-audit

With Makefile: make install, make test, make audit, or make check (CI-equivalent). make build / make upload for releases (upload requires twine credentials).

Live integration tests: make livetest runs live_tests/ with pytest -vv -s (verbose + uncaptured stderr) when OSIDB_LIVE_TEST=1 and normal OSIDB_* credentials are set. Default assertions use CVE-2014-0160; optional OSIDB_LIVE_MIN_* env vars enforce minimum totals for your instance. Setup, count output, and .gitignore patterns for secrets are documented in live_tests/README.md. Default make test / pytest only run tests/ (offline).

On Debian/Ubuntu (including local containers), install libkrb5-dev before pip install so the gssapi dependency can find krb5-config (Kerberos stack used with osidb-bindings).

License

MIT — see LICENSE.