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 .

Related MCP server: Red Hat Lightspeed MCP

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. If an LLM agent is calling these tools, read 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.

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 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. 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.