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](TOOLS.md). If an LLM agent is calling these tools, read [Using with AI agents](#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](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](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.