openqa-mcp

An MCP server that exposes curated, typed tools over the openQA REST API. It is built on fastmcp 3.x and the openqa-async transport client.

Read tools work anonymously; mutating tools require API credentials and return 403 without them.

Install

uv sync

This installs the package and its dependencies into a project virtualenv and exposes the openqa-mcp console script.

Configuration

The server reads its configuration from environment variables, falling back to the openQA client config file for credentials.

Environment variables

OPENQA_API_KEY and OPENQA_API_SECRET only take effect when both are set; a partial pair is ignored so the client is never half-configured.

Config file

If the env credentials are not set, openqa-async loads them from ~/.config/openqa/client.conf (or /etc/openqa/client.conf). Generate a key/secret from the API keys page of your openQA instance and add a section keyed by the host:

[openqa.opensuse.org]
key = YOUR_API_KEY
secret = YOUR_API_SECRET

Without any credentials the server is GET-only (read tools succeed, mutating tools get 403).

Tools

Read tools

list_jobs and list_jobs_overview accept the same optional filters: state, result, distri, version, build, test, arch, machine, groupid, group, latest, limit, ids. list_jobs additionally accepts offset for pagination (the overview endpoint returns only the latest job per scenario and is not paginated). Unset filters are dropped from the request.

Both also accept summary (default False). The default full result can be very large (~1.5 MB / 150+ jobs for a populated build) and may be truncated by MCP clients. Pass summary=True for a compact per-result breakdown:

{
  "total": 156,
  "by_result": {"passed": 57, "softfailed": 61, "failed": 7, "...": 0},
  "by_state":  {"done": 136, "cancelled": 20},
  "by_arch":   {"x86_64": 78, "aarch64": 39, "s390x": 39},
  "jobs": {"failed": [{"id": 1, "test": "install", "arch": "x86_64"}], "...": []}
}

Jobs bucket by result; in-progress jobs (result none) bucket by state (e.g. running, scheduled). To work with the full data instead, save it to a temporary file and process it with jq, e.g. jq '.jobs[] | select(.result=="failed")'.

Mutating tools (require credentials)

Mutating tools carry the mutating tag so MCP clients can gate them behind confirmation. To drop them entirely, start the server in read-only mode with --readonly (or OPENQA_READONLY=true): the mutating tools are never registered, so clients see only the read tools.

Running

stdio (default)

Most local MCP clients spawn the server over stdio. Wire it in with:

uv run openqa-mcp

Example MCP client configuration:

{
  "mcpServers": {
    "openqa": {
      "command": "uv",
      "args": ["run", "openqa-mcp"],
      "env": {
        "OPENQA_SERVER": "openqa.opensuse.org"
      }
    }
  }
}

HTTP (optional)

For remote or shared deployments, run over HTTP with --http:

uv run openqa-mcp --http --server 127.0.0.1 --port 8000

The server can also be launched as a module:

uv run python -m openqa_mcp --http --port 8000

Flags override the environment, which supplies the defaults:

Press Ctrl-C to stop; the server shuts down cleanly and closes its client.

Development

uv run pytest        # run the test suite
uv run ruff check .  # lint