Amazon Braket Mcp Server

Amazon Braket MCP Server

A comprehensive Model Context Protocol (MCP) server that provides quantum computing capabilities through Amazon Braket. This server enables you to create, execute, and analyze quantum circuits directly from your command line interface, making quantum computing accessible and integrated into your development workflow.

> ⚠️ Important Notice: This is an unofficial project and is not officially supported by Amazon Web Services. However, it follows the implementation patterns and architectural structure of the official Amazon MCP servers available at https://github.com/awslabs/mcp, ensuring consistency with AWS MCP server standards and best practices.

🚀 Overview

This MCP server provides a complete quantum computing toolkit through Amazon Braket, enabling:

• Circuit Creation: Build quantum circuits using intuitive gate operations
• Pre-built Algorithms: Access common quantum circuits (Bell pairs, GHZ states, QFT)
• Multi-Device Support: Run on simulators and real quantum hardware
• Result Analysis: Visualize and analyze quantum measurement outcomes
• Task Management: Monitor, search, and manage quantum computing jobs
• Educational Tools: Perfect for learning quantum computing concepts

📦 Installation

pip install awslabs.amazon-braket-mcp-server

Dependencies

This server requires the following key dependencies:

• amazon-braket-sdk - Amazon Braket SDK for Python
• qiskit - Quantum computing framework
• qiskit-braket-provider - Qiskit provider for Amazon Braket
• matplotlib - For circuit and result visualization
• numpy - For numerical operations

⚙️ Configuration

AWS Credentials

The server requires AWS credentials with permissions to access Amazon Braket services. Configure using:

Environment Variables

The server supports several environment variables for configuration:

# AWS Configuration
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_REGION=us-east-1

# Braket-specific Configuration
export BRAKET_DEFAULT_DEVICE_ARN=arn:aws:braket:::device/quantum-simulator/amazon/sv1
export BRAKET_WORKSPACE_DIR=/path/to/your/workspace  # For saving visualizations

# Optional S3 Configuration
export BRAKET_S3_BUCKET=your-quantum-results-bucket
export BRAKET_S3_PREFIX=experiments/

1. AWS credentials file:

``bash aws configure ``

1. IAM roles: Use IAM roles when running on AWS services

Required AWS Permissions

Your AWS credentials need these permissions:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "braket:SearchDevices",
                "braket:GetDevice",
                "braket:CreateQuantumTask",
                "braket:GetQuantumTask",
                "braket:CancelQuantumTask",
                "braket:SearchQuantumTasks",
                "s3:GetObject",
                "s3:PutObject"
            ],
            "Resource": "*"
        }
    ]
}

Supported AWS Regions

• us-east-1 (US East - N. Virginia) - Recommended
• us-west-1 (US West - N. California)
• us-west-2 (US West - Oregon)
• eu-west-2 (Europe - London)
• ap-southeast-1 (Asia Pacific - Singapore)

🤖 Amazon Q CLI Integration

This MCP server is designed to work seamlessly with Amazon Q CLI, providing quantum computing capabilities through natural language interactions. Here's how to configure and use it:

Prerequisites

1. Install Amazon Q CLI:

```bash # Install Amazon Q CLI npm install -g @aws/amazon-q-cli

# Or using pip pip install amazon-q-cli ```

1. Install the Braket MCP Server:

``bash pip install awslabs.amazon-braket-mcp-server ``

Configuration

Option 1: Using Q CLI Configuration File

Create or update your Amazon Q CLI configuration file (~/.q/config.json):

{
  "mcpServers": {
    "amazon-braket": {
      "command": "python",
      "args": ["-m", "awslabs.amazon_braket_mcp_server"],
      "env": {
        "AWS_REGION": "us-east-1",
        "BRAKET_WORKSPACE_DIR": "/path/to/your/quantum-workspace"
      }
    }
  }
}

Option 2: Using Environment Variables

Set up your environment before starting Q CLI:

# AWS Configuration
export AWS_REGION=us-east-1
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key

# Braket-specific Configuration
export BRAKET_DEFAULT_DEVICE_ARN=arn:aws:braket:::device/quantum-simulator/amazon/sv1
export BRAKET_WORKSPACE_DIR=/path/to/your/quantum-workspace

# Optional S3 Configuration for storing results
export BRAKET_S3_BUCKET=your-quantum-results-bucket
export BRAKET_S3_PREFIX=experiments/

# Start Q CLI with MCP server
q chat --mcp-server amazon-braket

Option 3: Inline Configuration

Start Q CLI with inline MCP server configuration:

q chat --mcp-server "amazon-braket:python:-m:awslabs.amazon_braket_mcp_server"

Configuration Tips

1. Workspace Directory: Set BRAKET_WORKSPACE_DIR to organize your quantum experiments

``bash export BRAKET_WORKSPACE_DIR=~/quantum-experiments ``

1. Default Device: Configure your preferred simulator for quick testing

``bash export BRAKET_DEFAULT_DEVICE_ARN=arn:aws:braket:::device/quantum-simulator/amazon/sv1 ``

1. S3 Storage: Use S3 for persistent result storage

``bash export BRAKET_S3_BUCKET=my-quantum-results export BRAKET_S3_PREFIX=experiments/$(date +%Y-%m)/ ``

1. Cost Management: Set up billing alerts for quantum hardware usage

``bash # Q CLI can help monitor costs You: "How much have I spent on quantum computing this month?" ``

Troubleshooting Q CLI Integration

MCP Server Not Found

# Verify installation
pip list | grep amazon-braket-mcp-server

# Test server directly
python -m awslabs.amazon_braket_mcp_server --version

AWS Credentials Issues

# Test AWS access
aws sts get-caller-identity

# Verify Braket permissions
aws braket search-devices

Connection Problems

# Check Q CLI logs
q chat --debug --mcp-server amazon-braket

# Verify environment variables
env | grep -E "(AWS|BRAKET)"

🛠️ Available Tools

Circuit Creation Tools

create_quantum_circuit

Create custom quantum circuits with specific gates and operations.

Parameters:

• num_qubits (int): Number of qubits in the circuit
• gates (list): List of gate operations to apply

Example:

# Create a 3-qubit circuit with Hadamard and CNOT gates
circuit = create_quantum_circuit(
    num_qubits=3,
    gates=[
        {"name": "h", "qubits": [0]},           # Hadamard on qubit 0
        {"name": "cx", "qubits": [0, 1]},      # CNOT from qubit 0 to 1
        {"name": "ry", "qubits": [2], "params": [1.57]},  # Y-rotation on qubit 2
        {"name": "measure_all"}                 # Measure all qubits
    ]
)

Supported Gates:

• h - Hadamard gate (creates superposition)
• x, y, z - Pauli gates
• cx, cy, cz - Controlled gates
• rx, ry, rz - Rotation gates (require params)
• s, t - Phase gates
• measure_all - Measure all qubits

create_bell_pair_circuit

Create a Bell pair (maximally entangled two-qubit state).

Example:

# Creates |00⟩ + |11⟩ state (50% chance each)
bell_circuit = create_bell_pair_circuit()

Use Cases:

• Quantum entanglement demonstrations
• Quantum teleportation protocols
• Bell inequality tests

create_ghz_circuit

Create a GHZ (Greenberger-Horne-Zeilinger) state for multi-qubit entanglement.

Parameters:

• num_qubits (int, default=3): Number of qubits to entangle

Example:

# Create 4-qubit GHZ state: |0000⟩ + |1111⟩
ghz_circuit = create_ghz_circuit(num_qubits=4)

Use Cases:

• Multi-party quantum communication
• Quantum error correction studies
• Quantum sensing applications

create_qft_circuit

Create a Quantum Fourier Transform circuit.

Parameters:

• num_qubits (int, default=3): Number of qubits for QFT

Example:

# Create 3-qubit QFT circuit
qft_circuit = create_qft_circuit(num_qubits=3)

Use Cases:

• Shor's factoring algorithm
• Quantum phase estimation
• Period finding problems

Execution Tools

run_quantum_task

Execute quantum circuits on Braket devices.

Parameters:

• circuit (dict): Circuit definition from creation tools
• device_arn (str, optional): Specific device ARN
• shots (int, default=1000): Number of measurements
• s3_bucket (str, optional): S3 bucket for results
• s3_prefix (str, optional): S3 prefix for organization

Example:

# Run on state vector simulator
task = run_quantum_task(
    circuit=bell_circuit,
    device_arn="arn:aws:braket:::device/quantum-simulator/amazon/sv1",
    shots=1000
)

# Run on real quantum hardware (when available)
task = run_quantum_task(
    circuit=my_circuit,
    device_arn="arn:aws:braket:us-east-1::device/qpu/rigetti/Aspen-M-3",
    shots=100,
    s3_bucket="my-quantum-results",
    s3_prefix="experiments/2024/"
)

get_task_result

Retrieve results from completed quantum tasks.

Parameters:

• task_id (str): ARN of the quantum task

Example:

# Get results and analyze
results = get_task_result(task_id="arn:aws:braket:us-east-1:123456789:quantum-task/abc-123")

# Results include:
# - measurement counts: {"00": 487, "11": 513}
# - raw measurements: [[0,0], [1,1], [0,0], ...]
# - task metadata and timing

Device Management Tools

list_devices

List all available quantum devices and simulators.

Example:

devices = list_devices()

# Returns information about:
# - AWS simulators (SV1, TN1, DM1)
# - IonQ quantum computers
# - Rigetti quantum processors
# - Oxford Quantum Computing devices
# - Device status and availability

get_device_info

Get detailed information about a specific quantum device.

Parameters:

• device_arn (str): ARN of the device

Example:

device_info = get_device_info(
    device_arn="arn:aws:braket:::device/quantum-simulator/amazon/sv1"
)

# Returns:
# - Device capabilities and limitations
# - Supported gate sets
# - Connectivity topology
# - Pricing information
# - Current availability status

Task Management Tools

search_quantum_tasks

Search and filter quantum tasks by various criteria.

Parameters:

• device_arn (str, optional): Filter by device
• state (str, optional): Filter by task state (CREATED, RUNNING, COMPLETED, FAILED, CANCELLED)
• max_results (int, default=10): Maximum results to return
• days_ago (int, optional): Filter by creation time

Example:

# Find recent completed tasks
recent_tasks = search_quantum_tasks(
    state="COMPLETED",
    days_ago=7,
    max_results=20
)

# Find all tasks on a specific device
device_tasks = search_quantum_tasks(
    device_arn="arn:aws:braket:::device/quantum-simulator/amazon/sv1",
    max_results=50
)

cancel_quantum_task

Cancel a running quantum task.

Parameters:

• task_id (str): ARN of the task to cancel

Example:

# Cancel a long-running task
cancel_result = cancel_quantum_task(
    task_id="arn:aws:braket:us-east-1:123456789:quantum-task/long-running-task"
)

Visualization Tools

visualize_circuit

Generate visual representations of quantum circuits with AI-friendly descriptions.

Parameters:

• circuit (dict): Circuit definition to visualize

Response Format:

{
  "circuit_def": {...},
  "description": {
    "summary": "Bell pair circuit creating quantum entanglement between 2 qubits",
    "gate_sequence": [
      "Step 1: Apply Hadamard gate to qubit 0 (creates superposition)",
      "Step 2: Apply CNOT gate from qubit 0 to qubit 1 (creates entanglement)"
    ],
    "expected_behavior": "Creates Bell state |00⟩ + |11⟩, showing perfect correlation",
    "complexity": {"complexity_level": "low", "estimated_runtime": "fast"}
  },
  "ascii_visualization": "q0: ─H──●──M─\nq1: ────X──M─",
  "visualization_file": "/path/to/saved/circuit.png",
  "visualization_data": "base64_encoded_image",
  "usage_note": "Circuit visualization saved to file. Use image viewer for detailed diagram."
}

ASCII Circuit Examples:

Bell Pair Circuit:
q0: ─H──●──M─
q1: ────X──M─

GHZ State Circuit (3 qubits):
q0: ─H──●──│──M─
q1: ────X──●──M─
q2: ────│──X──M─

Custom Circuit with Rotations:
q0: ─H──●────────M─
q1: ────X──RY(π/4)─M─
q2: ─────────────M─

visualize_results

Create histograms and analysis from quantum measurement results.

Parameters:

• result (dict): Results from gettaskresult

Response Format:

{
  "result": {...},
  "description": {
    "summary": "Measured 2 different outcomes over 1000 shots. Most frequent: |11⟩ (55.0%)",
    "statistics": {
      "total_shots": 1000,
      "unique_outcomes": 2,
      "probabilities": {"00": 0.45, "11": 0.55},
      "entropy": 0.993
    },
    "insights": ["Results suggest quantum entanglement (Bell state pattern)"]
  },
  "ascii_visualization": "ASCII histogram of measurement results",
  "visualization_file": "/path/to/saved/results.png"
}

ASCII Results Example:

Measurement Results Histogram:
==================================================
|00⟩: ████████████████████████████████           45 ( 45.0%)
|11⟩: ████████████████████████████████████████   55 ( 55.0%)
==================================================
Total shots: 100

describe_visualization

Convert any visualization data into human-readable descriptions for AI model understanding.

Parameters:

• visualization_data (dict): Output from any visualization tool

Example:

# Get human-readable description of any visualization
description = describe_visualization(bell_circuit_response)

# Returns detailed analysis:
# - Circuit purpose and quantum phenomena
# - Step-by-step gate explanations  
# - Expected measurement patterns
# - Complexity and runtime estimates

🎨 Visualization Features

This MCP server includes advanced visualization capabilities designed to be AI model-friendly, providing both visual and textual representations of quantum circuits and results.

Key Features

🔤 ASCII Circuit Diagrams

All circuits are automatically converted to ASCII representations that AI models can directly read and understand:

Bell Pair Circuit:
q0: ─H──●──M─
q1: ────X──M─

Quantum Fourier Transform:
q0: ─H──●────●────────────M─
q1: ────│──H──●──────────M─
q2: ────│─────│──H───────M─

📝 Human-Readable Descriptions

Every circuit and result includes detailed descriptions:

• Circuit Summary: "Bell pair circuit creating quantum entanglement between 2 qubits"
• Gate Sequence: Step-by-step explanations of each operation
• Expected Behavior: Predictions of quantum phenomena (entanglement, superposition)
• Complexity Analysis: Runtime estimates and difficulty levels

📊 Intelligent Results Analysis

Measurement results include automatic pattern detection:

• Quantum Phenomena Detection: Identifies Bell states, GHZ states, superposition patterns
• Statistical Analysis: Entropy calculations, probability distributions
• Correlation Analysis: Detects quantum entanglement signatures
• ASCII Histograms: Text-based visualization of measurement outcomes

💾 Automatic File Management

All visualizations are automatically saved with metadata:

• Timestamped Files: Organized in braket_visualizations/ directory
• Metadata Files: Include descriptions, creation time, and usage notes
• Usage Instructions: Clear guidance on viewing saved visualizations

Response Structure

All visualization tools now return comprehensive responses:

{
  "circuit_def": "Standard circuit definiti

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [petertilsen](https://github.com/petertilsen)
- **Source:** [petertilsen/amazon-braket-mcp-server](https://github.com/petertilsen/amazon-braket-mcp-server)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.