rosclaw-moveit2-mcp

ROSClaw-Native MoveIt2 MCP Server

Production-grade MCP server for MoveIt2 motion planning with ROSClaw OS integration. "Teach Once, Embody Anywhere. Share Skills, Shape Reality."

中文文档 | Documentation

---

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

pip install rosclaw-moveit2-mcp

Install from Source

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

# 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

# Terminal 2: Start MCP Server
rosclaw-moveit2-mcp

Or with explicit transport:

python -m rosclaw_moveit2_mcp.server --transport stdio

3. Configure MCP Client

Add to your MCP client configuration (e.g., Claude Desktop):

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

# 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

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

# 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

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

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

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

@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:

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:

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:

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

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

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

# 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

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

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

@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

# 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

# Check robot state
ros2 topic echo /joint_states

# Verify planning group
ros2 service call /planning_scene moveit_msgs/srv/GetPlanningScene

TF lookup fails

# Check TF tree
ros2 run tf2_tools view_frames

# Echo specific transform
ros2 topic echo /tf

---

Contributing

We welcome contributions! Please see 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 - Navigation MCP Server
• rosclaw-firewall - Digital Twin Firewall
• sdk_to_mcp - SDK to MCP Generator
• mjlab-mcp-server - MuJoCo Lab MCP Server

---

Citation

If you use ROSClaw in your research, please cite:

@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 for details.

---

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

---