rosclaw-moveit2-mcp

# ROSClaw-Native MoveIt2 MCP Server [](https://docs.ros.org) [](https://www.python.org/) [](https://opensource.org/licenses/Apache-2.0) [](https://modelcontextprotocol.io/) > Production-grade MCP server for MoveIt2 motion planning with ROSClaw OS integration. > **"Teach Once, Embody Anywhere. Share Skills, Shape Reality."** [中文文档](README.zh.md) | [Documentation](https://docs.rosclaw.org/moveit2-mcp) --- ## Overview `rosclaw-moveit2-mcp` is a ROSClaw-Native MCP (Model Context Protocol) server that bridges Large Language Models (LLMs) with MoveIt2 motion planning for robotic arms. It implements 6 ROSClaw-Native Standards for production-grade embodied AI applications. ### Key Features - **Asynchronous ROS 2 Actions**: Non-blocking action clients with async/await - **Flywheel-Ready Responses**: Structured JSON for Data Flywheel ingestion - **Digital Twin Firewall**: MuJoCo-based safety validation before real execution - **Graceful Preemption**: Active task tracking with cancel support - **State-Aware Affordance**: Local state machine prevents invalid operations - **Semantic Spatial Binding**: TF2 integration abstracts 3D math from LLM ### Supported Robots - Universal Robots UR5/UR5e - Franka Emika Panda - Kinova Gen3 - Any robot with MoveIt2 configuration --- ## Installation ### Prerequisites - ROS 2 Humble or Jazzy - Python 3.10+ - MoveIt2 installed ### Install from PyPI ```bash pip install rosclaw-moveit2-mcp ``` ### Install from Source ```bash git clone https://github.com/ros-claw/rosclaw-moveit2-mcp.git cd rosclaw-moveit2-mcp pip install -e ".[dev]" ``` --- ## Quick Start ### 1. Start ROS 2 and MoveIt2 ```bash # Terminal 1: Start ROS 2 source /opt/ros/humble/setup.bash ros2 launch your_robot_moveit_config demo.launch.py ``` ### 2. Start the MCP Server ```bash # Terminal 2: Start MCP Server rosclaw-moveit2-mcp ``` Or with explicit transport: ```bash python -m rosclaw_moveit2_mcp.server --transport stdio ``` ### 3. Configure MCP Client Add to your MCP client configuration (e.g., Claude Desktop): ```json { "mcpServers": { "rosclaw-moveit2": { "command": "rosclaw-moveit2-mcp", "transportType": "stdio" } } } ``` --- ## Available Tools | Tool | Description | ROSClaw Standard | |------|-------------|------------------| | `moveit_get_state` | Get current robot joint state | State-Aware | | `moveit_plan_and_execute_pose` | Move to Cartesian pose | Async Actions | | `moveit_plan_and_execute_pose_firewalled` | Move with MuJoCo validation | Firewall | | `moveit_cancel_action` | Cancel active motion | Preemption | | `moveit_lookup_tf_pose` | TF2 semantic pose lookup | TF2 Binding | | `moveit_get_active_tasks` | List active motions | State-Aware | --- ## Usage Examples ### Basic Motion Planning ```python # Move end-effector to a specific pose result = await moveit_plan_and_execute_pose( x=0.5, y=0.2, z=0.3, qx=0.0, qy=0.0, qz=0.0, qw=1.0, target_object_name="Pick up apple", planning_group="panda_arm" ) ``` ### Semantic Spatial Binding ```python # Use TF frames instead of coordinates result = await moveit_plan_and_execute_pose( x=0, y=0, z=0, # Overridden by TF lookup target_tf_frame="apple_link", # Automatic pose lookup target_object_name="Pick apple from table" ) ``` ### Firewalled Execution (Digital Twin Validation) ```python # Validate in MuJoCo before real execution result = await moveit_plan_and_execute_pose_firewalled( x=0.5, y=0.2, z=0.3, target_object_name="Safe pick operation" ) # Returns validation status in result.firewall_validated ``` ### Cancel Active Motion ```python # Preempt running motion result = await moveit_cancel_action( task_id="abc12345" ) ``` --- ## ROSClaw-Native Standards ### 1. Asynchronous ROS 2 Actions Non-blocking action clients using `rclpy.action.ActionClient` with async/await: ```python # Non-blocking execution result = await moveit_client.plan_and_execute_pose(...) # Other operations can run concurrently ``` ### 2. Flywheel-Ready Responses All responses are structured JSON for Data Flywheel ingestion: ```json { "status": "SUCCEEDED", "action_id": "abc12345", "action_type": "plan_and_execute_pose", "semantic_goal": "Pick up apple", "timestamp_start": 1234567890.0, "timestamp_end": 1234567895.0, "duration_seconds": 5.0, "pose_target": {...}, "execution": { "success": true, "error_code": null, "error_message": null }, "safety": { "firewall_validated": true, "violations": [] } } ``` ### 3. Firewall Integration MuJoCo-based validation before real execution: ```python @mujoco_firewall( model_path="src/rosclaw/specs/panda.xml", safety_level=SafetyLevel.STRICT ) async def moveit_plan_and_execute_pose_firewalled(...): # Only executes if MuJoCo validation passes ``` ### 4. Graceful Preemption Cancel active motions without system instability: ```python async def cancel_action(self, task_id: str) -> Dict[str, Any]: goal_handle = self._active_tasks[task_id] cancel_future = goal_handle.cancel_goal_async() cancel_result = await self._await_future(cancel_future) ``` ### 5. State-Aware Affordance Local state machine prevents invalid operations: ```python if self.state.is_moving: return MoveItActionResult( status=ActionStatus.REJECTED, error_message="Robot is already executing a motion." ) ``` ### 6. Semantic Spatial Binding TF2 integration abstracts 3D math from LLM: ```python # LLM just provides semantic frame names pose = await lookup_tf_pose("kitchen_table", "base_link") # No quaternion math required! ``` --- ## Architecture ``` ┌─────────────────────────────────────────────────────────────┐ │ LLM Agent (Claude, etc.) │ └─────────────────────────────────────────────────────────────┘ │ MCP Protocol ▼ ┌─────────────────────────────────────────────────────────────┐ │ ROSClaw-Native MoveIt2 MCP Server │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │ │ │ Async Action │ │ State Machine│ │ TF2 Semantic │ │ │ │ Client │ │ │ │ Binding │ │ │ └──────────────┘ └──────────────┘ └──────────────────┘ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │ │ │ Flywheel JSON│ │ Firewall │ │ Preemption │ │ │ │ Responses │ │ Validation │ │ Support │ │ │ └──────────────┘ └──────────────┘ └──────────────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ROS 2 Actions ▼ ┌─────────────────────────────────────────────────────────────┐ │ MoveIt2 Motion Planner │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Physical Robot Arm │ └─────────────────────────────────────────────────────────────┘ ``` --- ## Configuration ### Environment Variables | Variable | Default | Description | |----------|---------|-------------| | `ROS_NAMESPACE` | `` | ROS namespace prefix | | `MOVEIT_PLANNING_GROUP` | `panda_arm` | Default planning group | | `FIREWALL_MODEL_PATH` | `panda.xml` | MuJoCo model for validation | | `FIREWALL_SAFETY_LEVEL` | `STRICT` | Safety validation level | ### Robot Configuration Create `robot_config.yaml`: ```yaml planning_groups: - name: panda_arm base_link: panda_link0 end_effector: panda_hand joint_limits: panda_joint1: min: -2.8973 max: 2.8973 firewall: model_path: "models/panda.xml" safety_level: STRICT collision_pairs: - ["panda_hand", "obstacles"] ``` --- ## Development ### Setup Development Environment ```bash git clone https://github.com/ros-claw/rosclaw-moveit2-mcp.git cd rosclaw-moveit2-mcp # Create virtual environment python -m venv .venv source .venv/bin/activate # Install with dev dependencies pip install -e ".[dev]" ``` ### Running Tests ```bash # Run all tests pytest # Run with coverage pytest --cov=rosclaw_moveit2_mcp --cov-report=term-missing # Run specific test pytest tests/test_firewall.py -v ``` ### Code Quality ```bash # Format code ruff format . # Check linting ruff check . # Type checking mypy src/rosclaw_moveit2_mcp ``` --- ## Data Flywheel Integration All action results are structured for automatic Data Flywheel ingestion: ```python { "status": "SUCCEEDED", "semantic_goal": "Pick up apple", "pose_target": {...}, "trajectory": {...}, "execution": {...}, "safety": {...} } ``` This data feeds into: - **Skill Learning**: VLA model training - **Failure Analysis**: Automatic root cause analysis - **Policy Improvement**: RL fine-tuning --- ## Safety Features ### Digital Twin Firewall All motions validated in MuJoCo before real execution: ```python @mujoco_firewall( model_path="panda.xml", safety_level=SafetyLevel.STRICT ) ``` ### Self-Collision Prevention MoveIt2's built-in self-collision checking. ### Joint Limit Enforcement Hardware limits enforced by ROSClaw firewall. ### Emergency Stop Immediate cancellation via `moveit_cancel_action()`. --- ## Troubleshooting ### Server won't start ```bash # Check ROS 2 environment echo $ROS_DISTRO source /opt/ros/humble/setup.bash # Check MoveIt2 is running ros2 topic list | grep move_action ``` ### Motion planning fails ```bash # Check robot state ros2 topic echo /joint_states # Verify planning group ros2 service call /planning_scene moveit_msgs/srv/GetPlanningScene ``` ### TF lookup fails ```bash # Check TF tree ros2 run tf2_tools view_frames # Echo specific transform ros2 topic echo /tf ``` --- ## Contributing We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. ### Development Workflow 1. Fork the repository 2. Create a feature branch (`git checkout -b feature/amazing-feature`) 3. Commit changes (`git commit -m 'Add amazing feature'`) 4. Push to branch (`git push origin feature/amazing-feature`) 5. Open a Pull Request --- ## Related Projects - [rosclaw-nav2-mcp](https://github.com/ros-claw/rosclaw-nav2-mcp) - Navigation MCP Server - [rosclaw-firewall](https://github.com/ros-claw/rosclaw-firewall) - Digital Twin Firewall - [sdk_to_mcp](https://github.com/ros-claw/sdk_to_mcp) - SDK to MCP Generator - [mjlab-mcp-server](https://github.com/ros-claw/mjlab-mcp-server) - MuJoCo Lab MCP Server --- ## Citation If you use ROSClaw in your research, please cite: ```bibtex @software{rosclaw_moveit2_mcp, title = {ROSClaw-Native MoveIt2 MCP Server}, author = {{ROSClaw Team}}, year = {2025}, url = {https://github.com/ros-claw/rosclaw-moveit2-mcp} } ``` --- ## License This project is licensed under the Apache License 2.0 - see [LICENSE](LICENSE) for details. --- ## Support - 📖 [Documentation](https://docs.rosclaw.org/moveit2-mcp) - 🐛 [Issue Tracker](https://github.com/ros-claw/rosclaw-moveit2-mcp/issues) - 💬 [Discussions](https://github.com/ros-claw/rosclaw-moveit2-mcp/discussions) --- <p align="center"> <strong>ROSClaw - Embodied Intelligence Operating System</strong><br> <em>Teach Once, Embody Anywhere. Share Skills, Shape Reality.</em> </p>