GEANT4 Simulation with MCP Server

A complete GEANT4 particle physics simulation system using Python bindings, integrated with Claude Desktop via Model Context Protocol (MCP) server. Fully containerized with Docker for easy deployment on macOS, Windows, and Linux.

Ready to Use: Clone this repo and run with Docker - no manual GEANT4 installation required!

Features

• GEANT4 Python Simulation: Full particle physics simulation using GEANT4 Python bindings

• Configurable Parameters:

  • Particle type (gamma, e-, e+, proton, neutron, etc.)

  • Particle energy (MeV)

  • Cubic detector dimensions (configurable X, Y, Z)

  • Detector material (various GEANT4 materials)

• MCP Server Integration: Control simulations directly from Claude Desktop

• Docker Container: Complete isolated environment with all dependencies

• JSON Output: Easy-to-parse simulation results

• ROOT File Support: Output data in ROOT TTree format for advanced analysis

• Plotting Tools: Generate physics plots directly from Claude Desktop

• Cross-Platform: Works on macOS, Windows (WSL2), and Linux

Related MCP server: FreeCAD MCP

What Users Get

After cloning this repository, users can:

1. Build and run in 3 commands:

   git clone https://github.com/abhich2507/geant4-mcp.git
   cd geant4-mcp
   docker-compose up -d

2. Control from Claude Desktop - Configure and run simulations through natural language

3. No GEANT4 installation needed - Everything is containerized

4. Complete working example - Default configuration runs out of the box

Quick Start

Prerequisites

• macOS/Linux: Docker Desktop installed

• Windows: Docker Desktop with WSL2 enabled

• Claude Desktop application

• 10+ GB disk space

• 8+ GB RAM recommended

1. Build and Start Docker Container

macOS/Linux:

# Build the Docker image (this will take 30-60 minutes for GEANT4)
docker-compose build

# Start the container
docker-compose up -d

Windows (PowerShell or Command Prompt):

# Build the Docker image (this will take 30-60 minutes for GEANT4)
docker-compose build

# Start the container
docker-compose up -d

Note for Windows: Make sure Docker Desktop is running and WSL2 integration is enabled in Settings → Resources → WSL Integration.

2. Configure Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS:

Location: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "geant4-simulation": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "geant4-simulation",
        "python3",
        "/workspace/mcp_server.py"
      ],
      "env": {
        "PYTHONPATH": "/opt/geant4/lib"
      }
    }
  }
}

Windows:

Location: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "geant4-simulation": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "geant4-simulation",
        "python3",
        "/workspace/mcp_server.py"
      ],
      "env": {
        "PYTHONPATH": "/opt/geant4/lib"
      }
    }
  }
}

Windows Tip: You can open this location by typing %APPDATA%\Claude in Windows Explorer address bar or by running:

notepad "$env:APPDATA\Claude\claude_desktop_config.json"

Linux:

Location: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "geant4-simulation": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "geant4-simulation",
        "python3",
        "/workspace/mcp_server.py"
      ],
      "env": {
        "PYTHONPATH": "/opt/geant4/lib"
      }
    }
  }
}

3. Restart Claude Desktop

macOS:

pkill -9 "Claude" && open -a "Claude"

Windows:

• Close Claude Desktop completely (check system tray)

• Reopen from Start Menu

Linux:

killall claude && claude &

4. Use from Claude Desktop

You can now control the simulation from Claude Desktop:

Configure a simulation with:
- 1 MeV gamma particles
- 20x20x20 cm water cube
- Run 1000 events

Manual Usage (Without Claude Desktop)

Run Simulation Directly

macOS/Linux:

# Enter the container
docker exec -it geant4-simulation bash

# Run with default configuration
python3 simulation.py

# Run with custom configuration
python3 simulation.py config.json

Windows (PowerShell):

# Enter the container
docker exec -it geant4-simulation bash

# Run with default configuration
python3 simulation.py

# Run with custom configuration
python3 simulation.py config.json

Run MCP Server Standalone

docker exec -it geant4-simulation python3 mcp_server.py

Available MCP Tools

When using Claude Desktop, the following tools are available:

1. configure_simulation

Configure simulation parameters:

• particle_type: Particle type (gamma, e-, e+, proton, etc.)

• particle_energy: Energy in MeV

• particle_position: Initial position [x, y, z] in cm

• particle_direction: Direction vector [x, y, z]

• cube_size_x/y/z: Detector dimensions in cm

• cube_material: Material (G4_WATER, G4_Al, G4_Pb, etc.)

• num_events: Number of events to simulate

2. run_simulation

Run the simulation with current configuration

3. get_simulation_status

Get current configuration and status

4. get_results

Retrieve detailed simulation results

5. save_configuration

Save current configuration to file

6. load_configuration

Load configuration from file

Configuration File Format

{
  "particle": {
    "type": "gamma",
    "energy_MeV": 1.0,
    "position_cm": [0.0, 0.0, -10.0],
    "direction": [0.0, 0.0, 1.0]
  },
  "detector": {
    "cube_size_x_cm": 10.0,
    "cube_size_y_cm": 10.0,
    "cube_size_z_cm": 10.0,
    "material": "G4_WATER"
  },
  "simulation": {
    "num_events": 100,
    "output_file": "output/simulation_results.json"
  }
}

Output Format

Results are saved in JSON format:

{
  "config": { ... },
  "results": [
    {
      "event_id": 0,
      "primary": { ... },
      "energy_deposited_MeV": 0.85,
      "tracks_created": 5,
      "interactions": 3
    }
  ],
  "summary": {
    "total_events": 100,
    "total_energy_deposited_MeV": 87.3,
    "avg_energy_deposited_MeV": 0.873
  }
}

Common Materials

• G4_WATER: Water

• G4_Al: Aluminum

• G4_Pb: Lead

• G4_Fe: Iron

• G4_Cu: Copper

• G4_AIR: Air

• G4_CONCRETE: Concrete

• G4_TISSUE_SOFT_ICRP: Soft tissue

Common Particles

• gamma: Photons

• e-: Electrons

• e+: Positrons

• proton: Protons

• neutron: Neutrons

• alpha: Alpha particles

• mu-: Muons

Development

Project Structure

geant4-mcp/
├── simulation.py          # Main GEANT4 simulation
├── mcp_server.py         # MCP server for Claude Desktop
├── Dockerfile            # Docker image definition
├── docker-compose.yml    # Docker compose configuration
├── requirements.txt      # Python dependencies
├── config.json          # Default configuration
├── output/              # Simulation results
└── README.md           # This file

Rebuilding After Changes

macOS/Linux:

# Rebuild container
docker-compose build

# Restart container
docker-compose restart

Windows (PowerShell):

# Rebuild container
docker-compose build

# Restart container
docker-compose restart

Viewing Logs

All Platforms:

# View MCP server logs
docker-compose logs -f

# View container logs
docker logs geant4-simulation

Troubleshooting

Container won't start

macOS/Linux:

docker-compose down
docker-compose up -d
docker-compose logs

Windows (PowerShell):

docker-compose down
docker-compose up -d
docker-compose logs

Claude Desktop doesn't see the server

1. Check container is running: docker ps

2. Verify configuration file location:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • Linux: ~/.config/Claude/claude_desktop_config.json

3. Restart Claude Desktop completely

4. Check MCP server logs in Claude Desktop Developer Tools

Windows-Specific Issues

Docker not found

• Ensure Docker Desktop is installed and running

• Check that Docker Desktop is set to start on login

• Verify WSL2 is enabled: wsl --status in PowerShell

WSL2 Integration Issues

1. Open Docker Desktop Settings

2. Go to Resources → WSL Integration

3. Enable integration with your WSL2 distro

4. Click "Apply & Restart"

Permission Denied Errors

• Run PowerShell/Command Prompt as Administrator

• Ensure your user is in the docker-users group

Path Issues in Windows

If you see path-related errors, ensure you're using forward slashes in Docker commands or let Docker handle the path conversion automatically.

Python import errors

The GEANT4 Python bindings may take a long time to compile. Wait for the initial build to complete.

Performance Notes

• First Build: 30-60 minutes (GEANT4 compilation)

• Container Start: ~10 seconds

• Simulation Speed: ~100-1000 events/second (depends on complexity)

• Windows Note: Performance with WSL2 is comparable to native Linux. If using Hyper-V backend, expect 10-20% slower compilation times.

Platform-Specific Notes

macOS

• Apple Silicon (M1/M2/M3): Docker runs via Rosetta 2 translation layer. First build may take longer.

• Intel Macs: Native x86_64 performance.

• Configuration location: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows

• Requires: Windows 10/11 with WSL2 enabled

• Docker Backend: WSL2 backend recommended (not Hyper-V)

• File Performance: Keep project files in WSL2 filesystem for better performance

• Configuration location: %APPDATA%\Claude\claude_desktop_config.json

• To access WSL filesystem: \\wsl$\Ubuntu\home\<username>\

Linux

• Native Performance: Best performance on native Linux

• Docker: Requires docker and docker-compose installed

• Configuration location: ~/.config/Claude/claude_desktop_config.json

Requirements

All Platforms

• Claude Desktop application

• 10+ GB disk space

• 8+ GB RAM recommended

macOS

• macOS 11+ (Big Sur or later)

• Docker Desktop for Mac

Windows

• Windows 10/11 (64-bit)

• WSL2 enabled

• Docker Desktop for Windows

• Ubuntu WSL2 distro (recommended)

Linux

• Modern Linux distribution (Ubuntu 20.04+, Fedora 35+, etc.)

• Docker Engine or Docker Desktop

• docker-compose

Installation Guides

Windows Setup from Scratch

1. Enable WSL2:

   # Run in PowerShell as Administrator
   wsl --install
   # Restart computer

2. Install Ubuntu on WSL2:

   wsl --install -d Ubuntu
   # Set up username and password when prompted

3. Install Docker Desktop:

   • Download from: https://www.docker.com/products/docker-desktop

   • Install and enable WSL2 integration

   • Go to Settings → Resources → WSL Integration

   • Enable integration with Ubuntu

4. Clone project in WSL2:

   # Open Ubuntu terminal
   cd ~
   git clone <repository-url>
   cd geant4-mcp

5. Continue with Quick Start section above

macOS Setup from Scratch

1. Install Homebrew (if not already installed):

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Install Docker Desktop:

   brew install --cask docker
   # Or download from: https://www.docker.com/products/docker-desktop

3. Open Docker Desktop and complete setup

4. Continue with Quick Start section above

Linux Setup from Scratch

1. Install Docker (Ubuntu/Debian):

   sudo apt-get update
   sudo apt-get install docker.io docker-compose
   sudo systemctl start docker
   sudo systemctl enable docker
   sudo usermod -aG docker $USER
   # Log out and back in for group changes to take effect

2. For other distros, see: https://docs.docker.com/engine/install/

3. Continue with Quick Start section above

What Users Need

Users only need to have installed:

• Git (to clone the repository)

• Docker Desktop (for their platform)

• Claude Desktop (to use the MCP integration)

Everything else is handled automatically by Docker!

Repository Setup

If you haven't pushed to GitHub yet:

# Initialize git (if needed)
git init

# Add all files
git add .

# Commit
git commit -m "Initial commit: GEANT4 simulation with MCP server"

# Add your GitHub repository as remote
git remote add origin https://github.com/<your-username>/geant4-mcp.git

# Push to GitHub
git branch -M main
git push -u origin main

Recommended GitHub Settings

1. Add Topics/Tags:

   • geant4

   • particle-physics

   • simulation

   • mcp-server

   • docker

   • claude-desktop

   • python

2. Add Description:

   "GEANT4 particle physics simulation with MCP server integration for Claude Desktop. Fully containerized with Docker."

3. Enable Issues - So users can report problems or ask questions

4. Add GitHub Actions (optional) - For automated Docker builds

License

This project is licensed under the MIT License - see the LICENSE file for details.

This software uses GEANT4, which is distributed under the Geant4 Software License.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Citation

If you use this software in your research, please cite:

@software{geant4_mcp_2025,
  title={GEANT4 Simulation with MCP Server},
  author={Your Name},
  year={2025},
  url={https://github.com/<your-username>/geant4-mcp}
}

Acknowledgments

• GEANT4 Collaboration for the particle physics simulation toolkit

• Anthropic for Claude Desktop and MCP protocol

• CERN ROOT for data analysis framework