# Amazon Braket Mcp Server

> amazon braket mcp server implementation

- **Type:** MCP server
- **Install:** `agentstack add mcp-petertilsen-amazon-braket-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [petertilsen](https://agentstack.voostack.com/s/petertilsen)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [petertilsen](https://github.com/petertilsen)
- **Source:** https://github.com/petertilsen/amazon-braket-mcp-server

## Install

```sh
agentstack add mcp-petertilsen-amazon-braket-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](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

```bash
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:

```bash
# 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/
```

2. **AWS credentials file**: 
   ```bash
   aws configure
   ```

3. **IAM roles**: Use IAM roles when running on AWS services

### Required AWS Permissions
Your AWS credentials need these permissions:
```json
{
    "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
   ```

2. **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`):

```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:

```bash
# 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:

```bash
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
   ```

2. **Default Device**: Configure your preferred simulator for quick testing
   ```bash
   export BRAKET_DEFAULT_DEVICE_ARN=arn:aws:braket:::device/quantum-simulator/amazon/sv1
   ```

3. **S3 Storage**: Use S3 for persistent result storage
   ```bash
   export BRAKET_S3_BUCKET=my-quantum-results
   export BRAKET_S3_PREFIX=experiments/$(date +%Y-%m)/
   ```

4. **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**
```bash
# Verify installation
pip list | grep amazon-braket-mcp-server

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

#### **AWS Credentials Issues**
```bash
# Test AWS access
aws sts get-caller-identity

# Verify Braket permissions
aws braket search-devices
```

#### **Connection Problems**
```bash
# 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:**
```python
# 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:**
```python
# 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:**
```python
# 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:**
```python
# 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:**
```python
# 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:**
```python
# 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:**
```python
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:**
```python
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:**
```python
# 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:**
```python
# 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:**
```json
{
  "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 get_task_result

**Response Format:**
```json
{
  "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:**
```python
# 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:

```json
{
  "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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-petertilsen-amazon-braket-mcp-server
- Seller: https://agentstack.voostack.com/s/petertilsen
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.