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 filePSIANIMATOR_TRANSPORT- Transport protocol (stdio/websocket)PSIANIMATOR_HOST- Host for WebSocket transportPSIANIMATOR_PORT- Port for WebSocket transport
Quantum Settings:
PSIANIMATOR_QUANTUM_PRECISION- Quantum computation precisionPSIANIMATOR_MAX_HILBERT_DIM- Maximum Hilbert space dimensionPSIANIMATOR_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 LICENSE for details.
Contributing
We welcome contributions! Please see CONTRIBUTING.md 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