Content
# 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>
