Skip to main content
Glama
GJQ Runtime MCP Server

GJQ Runtime MCP Server

Official

GJQ-Runtime-MCP-Server

A Model Context Protocol (MCP) server that enables AI assistants to interact with the GuoJi Quantum Computing Cloud Platform via the gjq-client Python SDK.

Features

  • Account Management: Configure and view cloud platform credentials

  • Device Management: List backends, query configuration/calibration info, get the least busy backend

  • Compute Tasks: Submit sampling and estimation tasks from OpenQASM

  • Task Management: Poll status, get results/logs/details, list tasks

  • Example Circuits: Bell/GHZ/superposition/random, provided as MCP resources

Feature Showcase

Related MCP server: mcp-qiskit

Installation and Startup (using Cursor as an example)

  1. Clone the repository and create a virtual environment

git clone <this-repo>
cd gjq-runtime-mcp-server
python -m venv .venv

# Windows
.\.venv\Scripts\activate
# Linux/macOS
source .venv/bin/activate

pip install -e .
  1. Rename .env.example to .env, then set GJQ_API_KEY=your_api_key. (API key obtained from https://www.tiangongqs.com/cloud)

  2. Start the MCP Server locally (verify it runs first)

python -m gjq_runtime_mcp_server
  1. Create .cursor/mcp.json in the project root

# Windows(该行去除)
{
  "mcpServers": {
    "gjq-runtime": {
      "command": ".venv\\Scripts\\python.exe",
      "args": ["-m", "gjq_runtime_mcp_server"],
      "cwd": "/path/to/gjq-runtime-mcp-server",
      "env": { "GJQ_API_KEY": "你的_api_key" }
    }
  }
}

# Linux/macOS(该行去除)
{
  "mcpServers": {
    "gjq-runtime": {
      "command": ".venv/bin/python",
      "args": ["-m", "gjq_runtime_mcp_server"],
      "cwd": "/path/to/gjq-runtime-mcp-server",
      "env": { "GJQ_API_KEY": "你的_api_key" }
    }
  }
}
  1. Verify in Cursor

  • Fully exit the Cursor process and reopen it.

  • Use Ctrl + Shift + P to open Open Customize, select the MCPs tab.

  • Confirm that gjq-runtime is present, toggle it on, and check that a green dot appears.

MCP Tools

  • Account: setup_gjq_account_tool, active_account_info_tool

  • Devices: list_backends_tool, get_backend_configuration_tool, get_backend_properties_tool, least_busy_tool

  • Computation: sample_tool, estimate_tool

  • Tasks: get_task_status_tool, get_task_result_tool, get_task_log_tool, get_task_detail_tool, list_my_tasks_tool

All tools return {"status": "success" | "error", ...}.

OpenQASM 2.0 circuits work out of the box; to submit OpenQASM 3 circuits, install the parsing library additionally: pip install qiskit_qasm3_import.

MCP Resources

gjq://status, circuits://bell-state, circuits://ghz-state, circuits://superposition, circuits://random

Other MCP Client Configuration

The JSON above applies to JSON-based clients such as Cursor and Claude Desktop.

Client

Configuration File

Cursor

.cursor/mcp.json (project root)

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Codex

~/.codex/config.toml (TOML format, see below)

Codex uses TOML instead of JSON. Add the following to ~/.codex/config.toml (the top-level table name must be mcp_servers):

[mcp_servers.gjq-runtime]
command = "/path/to/gjq-runtime-mcp-server/.venv/bin/python"
args = ["-m", "gjq_runtime_mcp_server"]
cwd = "/path/to/gjq-runtime-mcp-server"

[mcp_servers.gjq-runtime.env]
GJQ_API_KEY = "你的_api_key"

Agent Skills

The accompanying skills are located in skills/gjq-quantum-runtime/. To use them in Cursor, copy that directory to .cursor/skills/ (project-level) or ~/.cursor/skills/ (personal-level).

Security Notes

  • The API key is stored in plaintext in ~/.gjq_client/gjq_client_account.json and in the env of the MCP client configuration. Treat it as confidential and never commit .env.

Development

pip install -e ".[test]"
pytest

License

Apache License 2.0

Available Tools

13 tools
active_account_info_toolA

Get the currently configured account info (api_key masked).

Inputs: no named parameters. Returns: object

estimate_toolB

Submit an expectation-estimation task.

observable is a list like [["ZZ", 1.0], ["XX", 0.5]] (Pauli string + coeff). Returns a task_id; fetch results with get_task_result_tool(task_id, observable).

Inputs: qasm (required), observable (required), backend_name (required), shots, +3 more. Returns: object

get_backend_configuration_toolC

Get the static configuration of a backend (basis gates, n_qubits, etc.).

Inputs: backend_name (required). Returns: object

get_backend_properties_toolC

Get calibration properties of a backend (T1/T2, gate errors). May be null.

Inputs: backend_name (required). Returns: object

get_task_detail_toolC

Get task details (backend, shots, submit time).

Inputs: task_id (required). Returns: object

get_task_log_toolC

Get the execution log of a task.

Inputs: task_id (required). Returns: object

get_task_result_toolA

Get the result of a task.

While the task is still running the result is empty and pending is true; check task_status to see the current state. Pass observable (same format as estimate_tool) to compute expectation values.

Inputs: task_id (required), observable. Returns: object

get_task_status_toolB

Get task status: INITIALIZING / QUEUED / RUNNING / DONE / ERROR / CANCELLED.

Inputs: task_id (required). Returns: object

least_busy_toolA

Return the name of the least busy available backend.

Inputs: no named parameters. Returns: object

list_backends_toolA

List all available quantum backends (devices/simulators).

Inputs: no named parameters. Returns: object

list_my_tasks_toolA

List the current user's tasks.

Inputs: no named parameters. Returns: object

sample_toolA

Submit a sampling task. Provide the circuit as an OpenQASM 2.0 string (OpenQASM 3 also works if the optional qiskit_qasm3_import is installed).

Returns a task_id; poll get_task_status_tool then get_task_result_tool. SAS-CPU simulator requires amplitude_index.

Inputs: qasm (required), backend_name (required), shots, transpile, +2 more. Returns: object

setup_gjq_account_toolA

Configure and cache the GuoJi Quantum cloud account credentials.

The api_key is persisted to ~/.gjq_client/gjq_client_account.json for reuse.

SECURITY: the api_key is passed as a tool argument, so it can end up in the LLM context and in client/transport logs. Prefer setting the GJQ_API_KEY environment variable; use this tool only in a trusted local setup.

Inputs: api_key (required), channel, base_url, backend_url. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 13 tools

    Disambiguation5/5

    All 13 tools have clearly distinct purposes. Account management, backend exploration, task submission, and task monitoring tools are well-separated with no overlapping functionality.

    Naming Consistency4/5

    Most tools follow a consistent verb_noun_tool pattern (e.g., get_backend_configuration_tool, list_backends_tool). However, 'estimate_tool', 'sample_tool', and 'least_busy_tool' deviate from the verb_noun structure, causing minor inconsistency.

    Tool Count5/5

    13 tools is appropriate for a quantum cloud runtime MCP server. It covers account setup, backend queries, task submission (estimate/sample), and full task lifecycle monitoring without being overwhelming or insufficient.

    Completeness4/5

    The tool set covers most of the expected workflow: account config, backend info, task submission, and result retrieval. A notable gap is the absence of a cancel task tool, which could be needed for long-running quantum tasks.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      This MCP server enables Claude Desktop to create, visualize, and simulate quantum circuits using Qiskit and Qiskit Aer, with support for preset circuits, custom QASM, and noise modeling.
      3
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server exposing Qiskit quantum computing functionality through the Model Context Protocol. Enables LLMs to create, manipulate, and execute quantum circuits via standardized MCP tools and resources.
      39 PyPI
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server for quantum device physics laboratory instrumentation control, enabling LLMs to interact with physics instruments and measurement systems through QCodes and JupyterLab.
      39
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      An MCP server that provides real-time IBM Quantum device data including queue depths, error rates, and coherence times, enabling AI assistants to query and compare quantum hardware.
      8
      MIT