qhub-mcp 1.8.0

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

One-click install (recommended): download qhub-mcp.mcpb from the latest release and double-click it, drag it into Claude Desktop, or install via Settings → Extensions → Advanced settings → Install Extension. Claude Desktop prompts for your personal access token on install and stores it in the OS keychain. uv must be installed on your machine — see the Prerequisites section.

Manual setup: 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>"
         }
       }
     }
   }
   

Building the MCPB package

The Claude Desktop one-click installer is shipped as an .mcpb file built from mcpb/manifest.json. To rebuild it locally:

npm install -g @anthropic-ai/mcpb
mcpb pack ./mcpb qhub-mcp.mcpb

# or with npx:
npx @anthropic-ai/mcpb pack ./mcpb qhub-mcp.mcpb

The resulting qhub-mcp.mcpb can be double-clicked to install into Claude Desktop. See the MCPB documentation for details on the format.

Debugging

Use the MCP Inspector to interactively explore the server's tools, inspect requests and responses, and troubleshoot issues:

npx @modelcontextprotocol/inspector uvx qhub-mcp

To inspect a local checkout instead of the published package:

npx @modelcontextprotocol/inspector uv --directory <PROJECT_PATH> run src/qhub_mcp/server.py

Authentication follows the same order as the server itself (see Authentication). Pass the token inline if you are not using qhubctl:

KQH_PERSONAL_ACCESS_TOKEN=<TOKEN> npx @modelcontextprotocol/inspector uvx qhub-mcp