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 .

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

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

python -m gjq_runtime_mcp_server

4. 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" }
    }
  }
}

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

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