PsiAnimator-MCP

manasp21/PsiAnimator-MCP

3.2

If you are the rightful owner of PsiAnimator-MCP and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

PsiAnimator-MCP is a Model Context Protocol server designed to integrate quantum physics computations with high-quality visualizations.

Tools

  1. create_quantum_state

    Create quantum states of various types, including pure, mixed, and coherent states.

  2. evolve_quantum_system

    Perform time evolution using methods like unitary, master equation, and Monte Carlo.

  3. measure_observable

    Conduct quantum measurements and analysis, including expectation values and variances.

  4. animate_quantum_process

    Generate animations for quantum processes, such as Bloch sphere evolution and state tomography.

  5. quantum_gate_sequence

    Apply quantum gates with visualization, including single-qubit and two-qubit gates.

PsiAnimator-MCP

Quantum Physics Simulation and Animation Server

A Model Context Protocol (MCP) server that integrates QuTip (Quantum Toolbox in Python) for quantum physics computations with Manim (Mathematical Animation Engine) for visualization.

Features

  • 🔬 Quantum Physics Engine: Complete state management, time evolution, and measurement tools
  • 🎬 Manim Animations: Publication-quality visualizations with quantum-specific scenes
  • 🔌 MCP Integration: Seamless integration with MCP-compatible clients
  • 🧮 Scientific Computing: Built on NumPy, SciPy, and QuTip for accuracy
  • 📊 Visualization Types: Bloch spheres, Wigner functions, state tomography, circuits
  • 🎓 Educational Focus: Perfect for quantum mechanics education and research

Installation

Quick Install

Option 1: One-line install (Unix/macOS)
curl -fsSL https://raw.githubusercontent.com/username/PsiAnimator-MCP/main/scripts/install.sh | bash
Option 2: PowerShell (Windows)
iwr https://raw.githubusercontent.com/username/PsiAnimator-MCP/main/scripts/install.ps1 | iex
Option 3: pip (when available on PyPI)
# Core installation (quantum computation only)
pip install psianimator-mcp

# Full installation with animation support
pip install "psianimator-mcp[animation]"

# Development installation
pip install "psianimator-mcp[dev,animation]"
Option 4: From source
git clone https://github.com/username/PsiAnimator-MCP.git
cd PsiAnimator-MCP
./scripts/install.sh --from-source

Prerequisites

  • Python ≥ 3.10
  • Git (for development installation)

For animation features:

  • LaTeX (for advanced mathematical rendering)
  • FFmpeg (for video generation)
  • Cairo graphics library (for high-quality rendering)

Installation Options Explained

🚀 Core Installation (Recommended for most users)

pip install psianimator-mcp
  • Includes all quantum computation features
  • MCP server functionality
  • QuTip, NumPy, SciPy for quantum physics
  • Works immediately without system dependencies

🎬 Animation Installation (For visualization)

pip install "psianimator-mcp[animation]"
  • Everything from core installation
  • Manim for generating animations
  • Requires system dependencies (LaTeX, FFmpeg)
  • Larger download and installation time

🔧 Development Installation

git clone https://github.com/username/PsiAnimator-MCP.git
cd PsiAnimator-MCP
pip install -e ".[dev,animation]"

Why Animation is Optional

Animation features (Manim) are kept optional because:

  • Heavy Dependencies: Manim requires LaTeX, FFmpeg, and Cairo which can be several GB
  • Installation Complexity: System dependencies can fail on different platforms
  • Use Case Separation: Many users only need quantum computation, not visualization
  • CI/Testing Reliability: Core features can be tested without system dependencies
  • Disk Space: Core installation is ~100MB vs ~2GB+ with full animation stack

Dependencies

Core dependencies (automatically installed):

  • QuTip ≥ 4.7.0 (quantum physics computations)
  • MCP ≥ 1.0.0 (Model Context Protocol)
  • NumPy, SciPy, matplotlib (scientific computing)
  • Pydantic, aiohttp (async web framework)

Animation dependencies (optional extras):

  • Manim ≥ 0.18.0 (mathematical animations)
  • h5py ≥ 3.9.0 (data storage)
  • pandas ≥ 2.0.0 (data analysis)

Post-Installation Setup

After installation, run the setup command:

psianimator-mcp setup

This will:

  • Create configuration directory (~/.config/psianimator-mcp/)
  • Copy example configuration file
  • Test installation and show feature availability
  • Provide Claude Desktop integration instructions

Verifying Installation

Check your installation status:

python -c "import psianimator_mcp; print(f'✅ Core: OK, Animation: {psianimator_mcp.is_animation_available()}')"

Expected outputs:

  • ✅ Core: OK, Animation: True - Full installation with animations
  • ✅ Core: OK, Animation: False - Core installation only

Troubleshooting

Import Errors

# If you get "No module named 'psianimator_mcp'"
pip install psianimator-mcp

# If you get animation-related errors
pip install "psianimator-mcp[animation]"

Animation Dependencies

# Ubuntu/Debian
sudo apt-get install texlive-latex-base ffmpeg libcairo2-dev

# macOS
brew install mactex ffmpeg cairo

# Windows
# Install MiKTeX, FFmpeg from official websites

Claude Desktop Integration

Automatic Configuration

Generate Claude Desktop configuration:

psianimator-mcp claude-config

Manual Configuration

Add to your Claude Desktop configuration file:

Windows: %USERPROFILE%\AppData\Roaming\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/claude-desktop/claude_desktop_config.json

{
  "mcpServers": {
    "psianimator-mcp": {
      "command": "python3",
      "args": ["-m", "psianimator_mcp.cli", "serve"],
      "env": {
        "PSIANIMATOR_CONFIG": "~/.config/psianimator-mcp/config.json"
      }
    }
  }
}

Note: Restart Claude Desktop after configuration changes.

Quick Start

1. Start the Server

Default (serves via MCP protocol):

psianimator-mcp

Stdio transport explicitly:

psianimator-mcp serve --transport stdio

WebSocket transport:

psianimator-mcp serve --transport websocket --port 3000

2. Test Installation

psianimator-mcp test

3. Basic Usage Example

import asyncio
from psianimator_mcp.tools.quantum_state_tools import create_quantum_state
from psianimator_mcp.tools.measurement_tools import measure_observable
from psianimator_mcp.server.config import MCPConfig

async def basic_example():
    config = MCPConfig()
    
    # Create a qubit in |0⟩ state
    result = await create_quantum_state({
        'state_type': 'pure',
        'system_dims': [2],
        'parameters': {'state_indices': [0]},
        'basis': 'computational'
    }, config)
    
    state_id = result['state_id']
    
    # Measure ⟨σz⟩
    measurement = await measure_observable({
        'state_id': state_id,
        'observable': 'sigmaz',
        'measurement_type': 'expectation'
    }, config)
    
    print(f"⟨σz⟩ = {measurement['measurement_results']['expectation_value']}")

asyncio.run(basic_example())

MCP Tools

1. create_quantum_state

Create quantum states of various types:

  • Pure states: |ψ⟩ (ket vectors)
  • Mixed states: ρ (density matrices)
  • Coherent states: |α⟩ (harmonic oscillator)
  • Squeezed states: reduced uncertainty
  • Thermal states: finite temperature
  • Fock states: definite photon number

2. evolve_quantum_system

Time evolution with multiple methods:

  • Unitary: Schrödinger equation (closed systems)
  • Master equation: Lindblad form (open systems)
  • Monte Carlo: Quantum trajectories
  • Stochastic: Continuous measurement

3. measure_observable

Quantum measurements and analysis:

  • Expectation values: ⟨O⟩
  • Variances: Δ²O
  • Probability distributions: P(outcome)
  • Correlation functions: ⟨A⟩⟨B⟩

4. animate_quantum_process

Generate Manim animations:

  • Bloch sphere evolution: Qubit dynamics
  • Wigner functions: Phase space representation
  • State tomography: Density matrix visualization
  • Circuit execution: Gate sequence animation
  • Energy levels: Population dynamics

5. quantum_gate_sequence

Apply quantum gates with visualization:

  • Single-qubit gates: Pauli, Hadamard, rotations
  • Two-qubit gates: CNOT, CZ, SWAP
  • Parameterized gates: RX, RY, RZ with custom angles
  • Circuit visualization: Step-by-step animation

6. calculate_entanglement

Compute entanglement measures:

  • Von Neumann entropy: S(ρ) = -Tr(ρ log ρ)
  • Concurrence: Two-qubit entanglement measure
  • Negativity: Partial transpose criterion
  • Mutual information: I(A:B)

Configuration

Configure via environment variables or MCPConfig:

from psianimator_mcp.server.config import MCPConfig

config = MCPConfig(
    quantum_precision=1e-12,
    max_hilbert_dimension=1024,
    animation_cache_size=100,
    output_directory="./output",
    render_backend="cairo"
)

Environment Variables

Configure PsiAnimator-MCP via environment variables:

Server Configuration:

  • PSIANIMATOR_CONFIG - Path to configuration file
  • PSIANIMATOR_TRANSPORT - Transport protocol (stdio/websocket)
  • PSIANIMATOR_HOST - Host for WebSocket transport
  • PSIANIMATOR_PORT - Port for WebSocket transport

Quantum Settings:

  • PSIANIMATOR_QUANTUM_PRECISION - Quantum computation precision
  • PSIANIMATOR_MAX_HILBERT_DIM - Maximum Hilbert space dimension
  • PSIANIMATOR_OUTPUT_DIR - Output directory for animations

Example:

export PSIANIMATOR_TRANSPORT=websocket
export PSIANIMATOR_PORT=3001
psianimator-mcp

CLI Commands

PsiAnimator-MCP provides several CLI commands:

psianimator-mcp                    # Start server (default: stdio)
psianimator-mcp serve              # Start server with options
psianimator-mcp config             # Show current configuration
psianimator-mcp setup              # Run post-installation setup
psianimator-mcp test               # Test installation
psianimator-mcp claude-config      # Generate Claude Desktop config
psianimator-mcp examples           # Show usage examples
psianimator-mcp version            # Show version
psianimator-mcp --help             # Show help

Command Examples

Start with custom config:

psianimator-mcp serve --config /path/to/config.json

WebSocket mode:

psianimator-mcp serve --transport websocket --host 0.0.0.0 --port 8080

Verbose logging:

psianimator-mcp serve -vvv

Examples

Comprehensive examples are provided in the examples/ directory:

  • basic_usage.py - Core functionality walkthrough
  • Bell state creation and entanglement analysis
  • Harmonic oscillator coherent state evolution
  • Multi-qubit quantum circuits

Run examples:

python examples/basic_usage.py

Development

Setup Development Environment

git clone https://github.com/username/PsiAnimator-MCP.git
cd PsiAnimator-MCP
pip install -e ".[dev]"
pre-commit install

Run Tests

pytest tests/

Code Quality

black src/ tests/
isort src/ tests/
mypy src/

Architecture

PsiAnimator-MCP/
├── src/psianimator_mcp/
│   ├── server/          # MCP server implementation
│   ├── quantum/         # Quantum physics engine
│   ├── animation/       # Manim visualization components
│   └── tools/           # MCP tool implementations
├── tests/               # Comprehensive test suite
├── examples/            # Usage examples
└── docs/               # Documentation

Limitations

  • Animation rendering requires sufficient system resources
  • Large Hilbert spaces (>1024 dimensions) may impact performance
  • Some advanced quantum error correction features are not yet implemented

License

MIT License - see for details.

Contributing

We welcome contributions! Please see for:

  • Development guidelines
  • Code standards
  • Testing requirements
  • Pull request process

Support

  • Documentation: See docs/API_REFERENCE.md
  • Examples: Check examples/ directory
  • Issues: Report bugs via GitHub issues