qhub-mcp 1.6.1

MCP server for the Kipu Quantum Hub

qhub-mcp

MCP server for the Kipu Quantum Hub. Exposes the Hub and Quantum Workloads APIs as tools for MCP-compatible agents and editors (Claude Desktop, Claude Code, Cursor, VS Code, and any other MCP client).

What it provides

Tools are grouped into two namespaces:

• hub_* — core Hub platform API (services, data pools, applications, use cases, ...)
• quantum_* — Quantum Workloads API (quantum jobs, sessions, backends, ...)

Plus a top-level run_subscribed_service tool to invoke services you are subscribed to.

Prerequisites

• Python >= 3.12
• uv (provides uvx)
• A Kipu Quantum Hub personal access token

Authentication

The server picks up credentials in the following order:

1. KQH_PERSONAL_ACCESS_TOKEN environment variable.
2. Credentials stored by qhubctl after qhubctl login -t <YOUR_PERSONAL_ACCESS_TOKEN>.

When you authenticate with qhubctl, the MCP server transparently reuses the same access token — no need to duplicate the token in your MCP client config. This is the recommended setup for local use so the token does not live in config files, and it keeps the CLI and the MCP server in sync on a single session.

Optional environment variables

• QHUB_API_BASE_URL — override the API base URL (defaults to https://api.hub.kipu-quantum.com). Useful for staging or self-hosted Hubs.

Configuration

The server is launched via uvx qhub-mcp. The snippets below show the minimal configuration for common MCP clients. Add the environment block from Option B if you prefer passing the token inline instead of using qhubctl.

Option A — with qhubctl (recommended): run qhubctl login -t <TOKEN> once, then use the config without an env block.

Option B — inline token: add "env": { "KQH_PERSONAL_ACCESS_TOKEN": "<TOKEN>" } to the server entry.

Claude Desktop

Edit claude_desktop_config.json (Settings → Developer → Edit Config) and add:

{
  "mcpServers": {
    "qhub-mcp": {
      "command": "uvx",
      "args": [
        "qhub-mcp"
      ]
    }
  }
}

Claude Code

Register the server with the CLI:

claude mcp add qhub-mcp -- uvx qhub-mcp

Or add it to .mcp.json / ~/.claude.json:

{
  "mcpServers": {
    "qhub-mcp": {
      "command": "uvx",
      "args": [
        "qhub-mcp"
      ]
    }
  }
}

Cursor

Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):

{
  "mcpServers": {
    "qhub-mcp": {
      "command": "uvx",
      "args": [
        "qhub-mcp"
      ]
    }
  }
}

VS Code

Register the server with the CLI:

code --add-mcp "{\"name\":\"qhub-mcp\",\"command\":\"uvx\",\"args\":[\"qhub-mcp\"]}"

Or add to your user or workspace settings.json (requires an MCP-capable extension such as GitHub Copilot Chat in agent mode):

{
  "mcp": {
    "servers": {
      "qhub-mcp": {
        "command": "uvx",
        "args": [
          "qhub-mcp"
        ]
      }
    }
  }
}

Other MCP clients

Any MCP client that supports stdio servers can launch qhub-mcp with:

• command: uvx
• args: ["qhub-mcp"]
• optional env: { "KQH_PERSONAL_ACCESS_TOKEN": "<TOKEN>", "QHUB_API_BASE_URL": "<URL>" }

Local development

1. Clone this repository.
2. Install uv if you don't have it.
3. Run uv sync.
4. Point your MCP client at the local checkout:

   {
     "mcpServers": {
       "qhub-mcp": {
         "command": "uv",
         "args": [
           "--directory",
           "<PROJECT_PATH>",
           "run",
           "src/qhub_mcp/server.py"
         ],
         "env": {
           "KQH_PERSONAL_ACCESS_TOKEN": "<YOUR_PERSONAL_ACCESS_TOKEN>"
         }
       }
     }
   }