Configuration

One-Click Setup

See Installation for the full one-click setup instructions.

# Linux / macOS
./scripts/setup_configure.sh --api-key YOUR_KEY --mcp claude-desktop

# Windows (PowerShell)
.\scripts\setup_configure.ps1 -ApiKey "YOUR_KEY" -McpClient claude-desktop

The scripts handle: dependency installation, API key configuration, and MCP client setup automatically.

Environment Variables

Variable	Description	Required	Default
QPANDA3_API_KEY	Your Origin Quantum API key	Yes	-
QPANDA3_CONFIG_PATH	Path to config file	No	-
QPANDA3_SERVER_URL	Override default server URL	No	https://qpanda3-runtime.qpanda.cn
QPANDA3_LOG_LEVEL	Log level (DEBUG, INFO, WARNING, ERROR)	No	INFO

Setting Your API Key

Option A: .env file (recommended)

cp .env.example .env
# Edit .env: QPANDA3_API_KEY=your_api_key

Option B: Environment variable

# Linux/macOS
export QPANDA3_API_KEY="your_api_key"

# Windows (PowerShell)
$env:QPANDA3_API_KEY="your_api_key"

Option C: config.yml

api_key: 'your_api_key_here'

MCP Client Configuration

Use the setup scripts (setup_configure.sh / setup_configure.ps1) to auto-configure MCP clients. The instructions below are for manual setup.

Replace /path/to/qpanda3-runtime-mcp-server with your actual project path. Windows users: Use .venv\Scripts\python.exe instead of .venv/bin/python.

Configuration Template

All MCP clients use the same configuration format:

{
  "mcpServers": {
    "qpanda3-runtime": {
      "command": "/path/to/qpanda3-runtime-mcp-server/.venv/bin/python",
      "args": ["-m", "qpanda3_runtime_mcp_server"],
      "cwd": "/path/to/qpanda3-runtime-mcp-server",
      "env": { "QPANDA3_API_KEY": "your_api_key" }
    }
  }
}

Client Config File Locations

Client	Config Location
Claude Code	~/.claude.json
Claude Desktop	See below
Cline	~/.vscode-server/data/User/globalStorage/saoudrizwan.cline/settings/cline_mcp_settings.json
Cursor	.cursor/mcp.json (project root)
Windsurf	~/.codeium/windsurf/mcp_config.json
Trae	.trae/mcp.json (project root)
Amazon Q	~/.aws/amazonq/mcp.json
Continue	.continue/mcpServers/mcp.json or ~/.continue/mcpServers/mcp.json
OpenCode	~/.config/opencode/opencode.json

!!! note "Claude Desktop Config Locations"

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Setup Script CLI Reference

Linux / macOS (setup_configure.sh)

./scripts/setup_configure.sh [OPTIONS]

Option	Description
--api-key KEY	Set API key directly
--mcp CLIENT	Configure specific client: claude-code, claude-desktop, cline, cursor
--interactive / -i	Interactive mode (prompts for API key and client)
--skip-deps	Skip dependency installation
--skip-mcp	Skip MCP client configuration

API key resolution order: --api-key > QPANDA3_API_KEY env > interactive prompt > .env.example fallback

Windows PowerShell (setup_configure.ps1)

.\scripts\setup_configure.ps1 [-ApiKey KEY] [-McpClient CLIENT] [-Interactive] [-SkipDeps] [-SkipMcpClient] [-ProjectDir DIR]

Same resolution order as above. The -ProjectDir parameter overrides the auto-detected project directory.

Troubleshooting

Problem	Solution
"No credentials provided"	Set QPANDA3_API_KEY env var or check .env file
"Authentication failed"	Verify your API key is correct
"Connection timeout"	Check network and firewall settings
ModuleNotFoundError	Run uv sync to install dependencies
Tools not available	Ensure QPANDA3_API_KEY is set in MCP config env block

Debug mode:

export QPANDA3_LOG_LEVEL=DEBUG
.venv/bin/python -m qpanda3_runtime_mcp_server --verbose