PsiAnimator-MCP

A server for quantum physics simulation and animation, using QuTip for computations and Manim for visualizations.

Quantum Physics Simulation and Animation Server

A Model Context Protocol (MCP) server that integratesQuTip(Quantum Toolbox in Python) for quantum physics computations withManim(Mathematical Animation Engine) for visualization.

curl -fsSL https://raw.githubusercontent.com/username/PsiAnimator-MCP/main/scripts/install.sh | bash

iwr https://raw.githubusercontent.com/username/PsiAnimator-MCP/main/scripts/install.ps1 | iex

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

git clone https://github.com/username/PsiAnimator-MCP.git cd PsiAnimator-MCP ./scripts/install.sh --from-source

- Python ≥ 3.10
- Git (for development installation)

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

🚀 Core Installation(Recommended for most users)

- 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

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

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

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)

After installation, run the setup command:

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

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

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

# If you get "No module named 'psianimator_mcp'" pip install psianimator-mcp # If you get animation-related errors pip install "psianimator-mcp[animation]"

# 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

Add to your Claude Desktop configuration file:

Windows:%USERPROFILE%\AppData\Roaming\Claude\claude_desktop_config.jsonmacOS:~/Library/Application Support/Claude/claude_desktop_config.jsonLinux:~/.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.

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

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())

- 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

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

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

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

- 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

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

Configure via environment variables orMCPConfig:

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" )

Configure PsiAnimator-MCP via environment variables:

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

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

export PSIANIMATOR_TRANSPORT=websocket export PSIANIMATOR_PORT=3001 psianimator-mcp

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

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

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

Comprehensive examples are provided in theexamples/directory:

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

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

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

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

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

We welcome contributions! Please seeCONTRIBUTING.mdfor:

An MCP server that allows AI assistants to interact with Adobe After Effects.