Geant4 MCP

基于MCP服务器的GEANT4仿真

使用Python绑定的完整GEANT4粒子物理模拟系统，通过模型上下文协议（MCP）服务器与Claude Desktop集成。完全容器化Docker，便于在macOS、Windows和Linux上部署。

准备使用：克隆此仓库并使用Docker运行-无需手动安装GEANT4！

特性

• GEANT4 Python模拟：使用GEANT4 Python绑定进行全粒子物理模拟
• 可配置参数:

- 粒子类型（伽马、e-、e+、质子、中子等） - 粒子能量（MeV） - 立方体探测器尺寸（可配置X、Y、Z） - 探测器材料（各种GEANT4材料）

• MCP服务器集成：直接从Claude Desktop进行控制模拟
• Docker容器：具有所有依赖关系的完整隔离环境
• JSON 输出：易于解析模拟结果
• ROOT文件支持：以ROOT TTree格式输出数据以进行高级分析
• 绘图工具：直接从Claude Desktop生成物理图
• 交叉平台的：适用于macOS、Windows（WSL2）和Linux

用户得到什么

克隆此存储库后，用户可以：

1. 用3个命令构建和运行:

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

1. 来自Claude Desktop的控制 -通过自然语言配置和运行模拟

1. 无需安装GEANT4 -一切都是集装箱化的

1. 完整的工作示例 -默认配置即用即用

快速开始

先决条件

• macOS/Linux：已安装Docker桌面
• 视窗：启用WSL2的Docker桌面
• Claude桌面应用程序
• 10+GB磁盘空间
• 建议使用8+GB RAM

1.构建并启动Docker容器

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或命令提示符）：

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

# Start the container
docker-compose up -d

Windows注意事项：确保Docker Desktop正在运行，并且在设置中启用了WSL2集成→ 资源→ WSL集成。

2.配置克劳德桌面

将以下内容添加到您的Claude Desktop配置文件中：

macOS：

位置: ~/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"
      }
    }
  }
}

窗户：

位置: %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提示：您可以通过键入以下内容打开此位置 %APPDATA%\Claude 在Windows资源管理器地址栏中或通过运行： ``powershell notepad "$env:APPDATA\Claude\claude_desktop_config.json" ``

Linux：

位置: ~/.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.重新启动克劳德桌面

macOS:

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

视窗:

• 完全关闭克劳德桌面（检查系统托盘）
• 从“开始”菜单重新打开

Linux:

killall claude && claude &

4.从克劳德桌面使用

现在，您可以从Claude Desktop控制模拟：

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

手动使用（不带Claude Desktop）

直接运行模拟

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

独立运行MCP服务器

docker exec -it geant4-simulation python3 mcp_server.py

可用的MCP工具

使用Claude Desktop时，可以使用以下工具：

1. configure_simulation

配置仿真参数：

• particle_type：粒子类型（伽马、e-、e+、质子等）
• particle_energy：能量单位为MeV
• particle_position：初始位置\[x，y，z\]，单位为厘米
• particle_direction：方向向量\[x，y，z\]
• cube_size_x/y/z：探测器尺寸（cm）
• cube_material：材料（G4_WATER、G4_Al、G4_Pb等）
• num_events：要模拟的事件数

2. run_simulation

使用当前配置运行模拟

3. get_simulation_status

获取当前配置和状态

4. get_results

检索详细的模拟结果

5. save_configuration

将当前配置保存到文件

6. load_configuration

从文件加载配置

配置文件格式

{
  "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"
  }
}

输出格式

结果以JSON格式保存：

{
  "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
  }
}

常用材料

• G4_WATER：水
• G4_Al：铝
• G4_Pb：领导
• G4_Fe：铁
• G4_Cu：铜
• G4_AIR：空气
• G4_CONCRETE：混凝土
• G4_TISSUE_SOFT_ICRP：软组织

常见粒子

• gamma：光子
• e-：电子
• e+：正电子
• proton：质子
• neutron：中子
• alpha：阿尔法粒子
• mu-：Muons

发展

项目结构

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

变更后的重建

macOS/Linux：

# Rebuild container
docker-compose build

# Restart container
docker-compose restart

Windows（PowerShell）：

# Rebuild container
docker-compose build

# Restart container
docker-compose restart

查看日志

所有平台：

# View MCP server logs
docker-compose logs -f

# View container logs
docker logs geant4-simulation

故障排除

容器无法启动

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看不到服务器

1. 检查容器是否正在运行： docker ps
2. 验证配置文件位置：

- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - 视窗: %APPDATA%\Claude\claude_desktop_config.json - Linux: ~/.config/Claude/claude_desktop_config.json

1. 完全重新启动克劳德桌面
2. 在Claude桌面开发工具中检查MCP服务器日志

Windows特定问题

找不到Docker

• 确保Docker Desktop已安装并正在运行
• 检查Docker Desktop是否设置为登录时启动
• 验证WSL2是否已启用： wsl --status 在PowerShell中

WSL2集成问题

1. 打开Docker桌面设置
2. 转到资源→ WSL 集成
3. 启用与WSL2发行版的集成
4. 点击“应用并重新启动”

权限被拒绝错误

• 以管理员身份运行PowerShell/命令提示符
• 确保您的用户在 docker-users 群组

Windows中的路径问题

如果你看到与路径相关的错误，请确保你在Docker命令中使用了正斜杠，或者让Docker自动处理路径转换。

Python导入错误

GEANT4 Python绑定可能需要很长时间才能编译。等待初始构建完成。

业绩说明

• 首次构建：30-60分钟（GEANT4汇编）
• 集装箱启动：约10秒
• 模拟速度：约100-1000个事件/秒（取决于复杂性）
• Windows注释WSL2的性能与原生Linux相当。如果使用Hyper-V后端，预计编译时间会慢10-20%。

平台特定注意事项

macOS

• 苹果硅（M1/M2/M3）Docker通过Rosetta 2翻译层运行。首次构建可能需要更长的时间。
• 英特尔Mac：本机x86_64性能。
• 配置位置： ~/Library/Application Support/Claude/claude_desktop_config.json

视窗

• 需要：启用WSL2的Windows 10/11
• Docker后端：建议使用WSL2后端（不是Hyper-V）
• 文件性能：将项目文件保存在WSL2文件系统中，以获得更好的性能
• 配置位置： %APPDATA%\Claude\claude_desktop_config.json
• 要访问WSL文件系统： \\wsl$\Ubuntu\home\\

Linux

• 本地性能：本机Linux上的最佳性能
• 码头工人：需要 docker 和 docker-compose 安装
• 配置位置： ~/.config/Claude/claude_desktop_config.json

需求

所有平台

• Claude桌面应用程序
• 10+GB磁盘空间
• 建议使用8+GB RAM

macOS

• macOS 11+（大苏尔或更高版本）
• Mac版Docker桌面

视窗

• Windows 10/11（64位）
• WSL2已启用
• Windows版Docker桌面
• Ubuntu WSL2发行版（推荐）

Linux

• 现代Linux发行版（Ubuntu 20.04+、Fedora 35+等）
• Docker引擎或Docker桌面
• docker编写

安装指南

Windows安装程序从头开始

1. 启用WSL2:

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

1. 在WSL2上安装Ubuntu:

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

1. 安装Docker桌面:

- 下载地址：https://www.docker.com/products/docker-desktop - 安装并启用WSL2集成 - 转到“设置”→ 资源→ WSL 集成 - 启用与Ubuntu的集成

1. 在WSL2中克隆项目:

   # Open Ubuntu terminal
   cd ~
   git clone 
   cd geant4-mcp

1. 继续上面的快速入门部分

macOS从头开始安装

1. 安装Homebrew （如果尚未安装）：

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

1. 安装Docker桌面:

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

1. 打开Docker桌面 并完成设置

1. 继续上面的快速入门部分

Linux安装程序从头开始

1. 安装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

1. 对于其他发行版，请参阅：https://docs.docker.com/engine/install/

1. 继续上面的快速入门部分

用户需要什么

用户只需安装：

• Git （克隆存储库）
• Docker 桌面版 （为他们的平台）
• 克劳德桌面版 （使用MCP集成）

其他一切都由Docker自动处理！

存储库设置

如果你还没有推送到GitHub：

# 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//geant4-mcp.git

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

推荐的GitHub设置

1. 添加主题/标签:

- geant4 - particle-physics - simulation - mcp-server - docker - claude-desktop - python

1. 添加描述:

> “用于Claude Desktop的GEANT4粒子物理模拟与MCP服务器集成。完全容器化Docker。”

1. 启用问题 -因此，用户可以报告问题或提问

1. 添加GitHub操作 （可选）-用于自动化Docker构建

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

该软件使用GEANT4，该软件在 Geant4软件许可证.

贡献

欢迎投稿！请参阅 贡献.md 作为指导方针。

引用

如果您在研究中使用此软件，请引用：

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

致谢

• GEANT4合作 粒子物理模拟工具包
• Anthropic 适用于Claude Desktop和MCP协议
• CERN根 数据分析框架