# Install pixi (if you don't have it)
curl -fsSL https://pixi.sh/install.sh | bash

# Clone and install
git clone https://github.com/kvgork/gazebo-mcp.git
cd gazebo-mcp
pixi install            # server only
# pixi install -e dev   # + pytest/ruff/mypy
# pixi install -e sim   # + full gz simulator (ros_gz)
# pixi install -e full  # everything

# Run the server
pixi run serve

# Install ROS2 Humble
sudo apt update
sudo apt install ros-humble-desktop

# Install Modern Gazebo (Recommended)
# For ROS2 Humble - Gazebo Fortress or Garden:
sudo apt install ros-humble-ros-gz

# Or for specific Gazebo version:
sudo apt install gz-harmonic  # Gazebo Harmonic
sudo apt install gz-garden    # Gazebo Garden
sudo apt install gz-fortress  # Gazebo Fortress

# Note: Classic Gazebo (gazebo-ros-pkgs) is deprecated
# Only install if you need legacy support:
# sudo apt install ros-humble-gazebo-ros-pkgs

# Clone the repository
git clone https://github.com/kvgork/gazebo-mcp.git
cd gazebo-mcp

# Source ROS2
source /opt/ros/humble/setup.bash

# Install Python dependencies
pip install -r requirements.txt

# Build the package (if using ROS2 workspace)
colcon build
source install/setup.bash

# Ensure ROS2 is sourced:
source /opt/ros/humble/setup.bash
source install/setup.bash  # If using colcon build

# Run the MCP server:
python -m gazebo_mcp.server

# Use Modern Gazebo (Default - Recommended)
export GAZEBO_BACKEND=modern

# Use Classic Gazebo (Deprecated)
export GAZEBO_BACKEND=classic

# Auto-detect based on running services
export GAZEBO_BACKEND=auto

# Set default world name for multi-world support (Modern only)
export GAZEBO_WORLD_NAME=default

# Set service call timeout (seconds)
export GAZEBO_TIMEOUT=5.0

export GAZEBO_MAX_FORCE_N=1000          # force magnitude cap (N)
export GAZEBO_MAX_TORQUE_NM=500         # torque magnitude cap (N·m)
export GAZEBO_MAX_JOINT_VELOCITY=10     # vel-mode joint cap (rad/s or m/s)
export GAZEBO_MAX_JOINT_EFFORT=500      # force/effort-mode joint cap (N·m or N)
export GAZEBO_MAX_PERSISTENT_WRENCHES=8 # max simultaneous persistent wrenches
export GAZEBO_RATE_LIMIT_HZ=50          # per-entity rate cap (Hz); <=0 disables
export GAZEBO_STRICT_BOUNDS=0           # 0 = clamp (default); 1 = reject over-limit

{
  "mcpServers": {
    "gazebo": {
      "command": "pixi",
      "args": ["run", "--manifest-path", "/path/to/gazebo-mcp/pixi.toml", "serve"]
    }
  }
}

{
  "mcpServers": {
    "gazebo": {
      "command": "python",
      "args": ["-m", "gazebo_mcp.server"],
      "cwd": "/path/to/gazebo_mcp_package",
      "env": {
        "PYTHONPATH": "/path/to/gazebo_mcp_package/src",
        "ROS_DOMAIN_ID": "0",
        "GAZEBO_BACKEND": "modern",
        "GAZEBO_WORLD_NAME": "default",
        "GAZEBO_TIMEOUT": "5.0"
      }
    }
  }
}

# Example: Claude controlling Gazebo via MCP

# 1. List all models in simulation
await use_mcp_tool("gazebo_list_models", {
    "response_format": "summary"
})

# 2. Spawn a model from file
await use_mcp_tool("gazebo_spawn_model", {
    "model_name": "my_robot",
    "model_file": "/path/to/robot.urdf",
    "pose": {
        "position": {"x": 0.0, "y": 0.0, "z": 0.5},
        "orientation": {"roll": 0, "pitch": 0, "yaw": 0}
    }
})

# 3. Get model state
state = await use_mcp_tool("gazebo_get_model_state", {
    "model_name": "my_robot"
})

# 4. List available sensors
await use_mcp_tool("gazebo_list_sensors", {
    "model_name": "my_robot"
})

# 5. Get sensor data
sensor_data = await use_mcp_tool("gazebo_get_sensor_data", {
    "sensor_name": "front_camera",
    "timeout": 5.0
})

# 6. Control simulation
await use_mcp_tool("gazebo_pause_simulation", {})
await use_mcp_tool("gazebo_unpause_simulation", {})

# 7. Get simulation status
status = await use_mcp_tool("gazebo_get_simulation_status", {})

# Run any example (no Gazebo required)
cd examples/
python 01_basic_connection.py
python 05_complete_workflow.py

ros2_gazebo_mcp/
├── src/gazebo_mcp/
│   ├── __init__.py
│   ├── bridge/
│   │   ├── __init__.py
│   │   ├── connection_manager.py    # ROS2 lifecycle management
│   │   └── gazebo_bridge_node.py    # Gazebo service interface
│   ├── tools/
│   │   ├── __init__.py
│   │   ├── model_management.py      # Model spawn/delete/list/state
│   │   ├── sensor_tools.py          # Sensor data queries
│   │   ├── world_tools.py           # World loading/properties
│   │   └── simulation_tools.py      # Simulation control
│   └── utils/
│       ├── __init__.py
│       ├── validators.py            # Input validation
│       ├── converters.py            # ROS2 ↔ Python conversions
│       ├── geometry.py              # Quaternion math, transforms
│       ├── exceptions.py            # Custom exceptions
│       ├── logger.py                # Structured logging
│       ├── metrics.py               # Performance metrics collection
│       └── profiler.py              # Tool profiling decorator
├── mcp/
│   ├── server/
│   │   ├── server.py                # Main MCP server (stdio protocol)
│   │   └── adapters/
│   │       ├── __init__.py
│   │       ├── model_management_adapter.py
│   │       ├── sensor_tools_adapter.py
│   │       ├── world_tools_adapter.py
│   │       ├── simulation_tools_adapter.py
│   │       ├── ros2_tools_adapter.py
│   │       └── developer_tools_adapter.py
│   └── README.md                    # MCP server documentation
├── tests/
│   ├── conftest.py                  # Pytest configuration
│   ├── test_integration.py          # Integration tests (80+ tests)
│   ├── test_utils.py                # Unit tests
│   └── README.md                    # Test documentation
├── examples/
│   ├── 01_basic_connection.py       # Basic MCP usage
│   ├── 02_spawn_and_control.py      # Model management
│   ├── 03_sensor_streaming.py       # Sensor data access
│   ├── 04_simulation_control.py     # Simulation control
│   ├── 05_complete_workflow.py      # Full robot testing workflow
│   └── README.md                    # Examples documentation
├── docs/
│   ├── IMPLEMENTATION_PLAN.md       # Original implementation plan
│   ├── PHASE3_PROGRESS.md           # Phase 3 progress tracking
│   ├── PHASE4_PLAN.md               # Phase 4 enhancements plan
│   ├── DEPLOYMENT.md                # Production deployment guide
│   ├── METRICS.md                   # Performance monitoring guide
│   └── ARCHITECTURE.md              # System architecture
├── deployment/
│   ├── gazebo-mcp.service           # systemd service file
│   └── install.sh                   # Production installation script
├── scripts/
│   └── show_metrics.py              # Metrics display and export
├── .github/workflows/
│   ├── test.yml                     # CI/CD pipeline
│   └── pre-commit.yml               # Pre-commit checks
├── Dockerfile                       # Multi-stage Docker build
├── docker-compose.yml               # Docker Compose configuration
├── .dockerignore                    # Docker ignore patterns
├── pyproject.toml                   # Python package configuration
├── package.xml                      # ROS2 package manifest
├── requirements.txt                 # Python dependencies
├── requirements-dev.txt             # Development dependencies
├── pytest.ini                       # Pytest configuration
└── README.md                        # This file

# ❌ Traditional approach - sends all 1000 models through model:
result = gazebo_list_models()  # 50,000+ tokens

# ✅ Our approach - filter locally in MCP server:
result = gazebo_list_models(response_format="summary")  # ~500 tokens (95% savings)

# Or get full data but filter client-side:
from skills.common.filters import ResultFilter
all_models = gazebo_list_models()["data"]["models"]
robots = ResultFilter.search(all_models, "robot", ["name"])
top_5 = ResultFilter.top_n_by_field(robots, "position.z", 5)
# Only 5 models sent to Claude instead of 1000! (95%+ savings)

# Start all services (Gazebo + MCP Server):
docker-compose up

# Run in background:
docker-compose up -d

# View logs:
docker-compose logs -f mcp_server

# Stop services:
docker-compose down

# Start with development container:
docker-compose --profile development up dev

# Run examples:
docker-compose exec mcp_server python3 examples/01_basic_connection.py

# View metrics:
docker-compose exec mcp_server python3 scripts/show_metrics.py

# Start with metrics exporter:
docker-compose --profile monitoring up

# Metrics exported to: ./metrics/metrics.prom (Prometheus format)

cd deployment
sudo ./install.sh

# Start service:
sudo systemctl start gazebo-mcp

# Check status:
sudo systemctl status gazebo-mcp

# View logs:
sudo journalctl -u gazebo-mcp -f

# Stop service:
sudo systemctl stop gazebo-mcp

# Unit tests (no ROS2 required):
pytest tests/test_utils.py -v

# Integration tests (ROS2 required):
source /opt/ros/humble/setup.bash
pytest tests/test_integration.py -v --with-ros2

# Full integration tests (Gazebo required):
# Terminal 1:
ros2 launch gazebo_ros gazebo.launch.py

# Terminal 2:
pytest tests/test_integration.py -v --with-gazebo

# Run all tests:
pytest tests/ -v

# Type checking (recommended):
mypy src/gazebo_mcp/

# Linting:
ruff check src/ tests/

# Formatting:
black src/ tests/

# Check ROS2 environment
echo $ROS_DISTRO  # Should show "humble" or "jazzy"

# Verify Gazebo installation
gz sim --version

# Check ROS2 topics
ros2 topic list

# Check Python version
python --version  # Should be 3.10+

# Verify dependencies
pip install -r requirements.txt

# Check ROS2 is sourced
source /opt/ros/humble/setup.bash

# Run server with logging
python -m gazebo_mcp.server 2>&1 | tee server.log

# Source ROS2 before running MCP server:
source /opt/ros/humble/setup.bash

# Verify rclpy is available:
python -c "import rclpy; print('rclpy OK')"

# Terminal 1 - Start Gazebo:
ros2 launch gazebo_ros gazebo.launch.py

# Terminal 2 - Run MCP server:
python -m gazebo_mcp.server

# Show summary:
python3 scripts/show_metrics.py

# Show detailed metrics:
python3 scripts/show_metrics.py --detailed

# Export to Prometheus:
python3 scripts/show_metrics.py --export metrics.prom --format prometheus

# Export to JSON:
python3 scripts/show_metrics.py --export metrics.json --format json

@software{gazebo_mcp,
  title = {Gazebo MCP Server: ROS2 Model Context Protocol for Gazebo},
  author = {Gazebo MCP Team},
  year = {2024},
  url = {https://github.com/kvgork/gazebo-mcp}
}