osidb-mcp

Python Model Context Protocol (MCP) server for OSIDB, built on osidb-bindings. Use it from Cursor, Claude Desktop, or any MCP client over stdio. Forked from vdanen/osidb-mcp with added write/mutation tools.

Install

pip install -e .
# or
uv pip install -e .

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

Using uvx (recommended — no pre-install required):

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

Or if osidb-mcp is already installed globally:

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

Default is OSIDB_MCP_PROFILE=full with readonly. The snippet above is the token-saving write setup: fewer advertised tools, mutations still available.

Tools

All MCP tools require a working OSIDB session (env + Kerberos or basic auth). 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.

Read-only tools

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

Write tools (readwrite mode only)

These tools are only registered when OSIDB_MCP_ACCESS_MODE=readwrite.

All write tools return {"ok": true, ...} on success. On partial failure (e.g. flaw created but a sub-resource failed), they return {"ok": true, "partial": true, "errors": [...]}.

Workflow model (OSIDB >= 5.12)

Workflow state is auto-classified based on flaw data completeness. No manual promote/reject actions are needed.

Workflows: DEFAULT, MANUAL, EMBARGOED, REJECTED. MANUAL and EMBARGOED skip ANALYSIS.

State progression (DEFAULT): NEW -> TRIAGE -> ANALYSIS -> PRE_SECONDARY_ASSESSMENT -> SECONDARY_ASSESSMENT -> DONE

Each transition happens automatically when the flaw's data satisfies the state's requirements. Use workflow_get(flaw_id, verbose=True, next=True) to inspect requirements. Use history=true for classification change history.

• To approve (reach DONE): flaw_label_add(name='approved', label_type='workflow')
• To reject: flaw_label_add(name='rejected', label_type='workflow') (auto-classifies into REJECTED:DONE)

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. Use that `uuid` as flaw_id when there is no CVE.
• `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: Set `OSIDB_MCP_PROFILE=lifecycle` (or core) so Cursor does not inject unused tool names. 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).
• Use two MCP entries (readonly vs readwrite) so mutations only happen 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 dev (or make sync) installs dev dependencies with uv; make test, make audit, and make check run local checks. make install remains available for pip-based installs.

For PyPI Trusted Publishing setup and the shared make version VERSION=x.y.z / make brew release workflow, see RELEASING.md.

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.