Robotics MCP Server

Unified robotics control via MCP - Physical and virtual robots (bot + vbot)

License

🎯 Overview

Robotics MCP Server provides unified control for both physical robots (ROS-based) and virtual robots (Unity/VRChat), with a focus on Moorebot Scout, Unitree robots, and virtual robotics testing.

Key Features

Physical Robot Control: Moorebot Scout (ROS 1.4), Unitree Go2/G1
YDLIDAR SuperLight (95g) LiDAR integration for Scout
Virtual Robot Control: Unity3D/VRChat/Resonite integration via existing MCP servers
ROS Bridge Integration: ROS 1.4 (Melodic) via rosbridge_suite
Multi-Robot Coordination: Physical and virtual robots together
World Labs Marble/Chisel: Environment generation and import
Dual Transport: stdio (MCP) + HTTP (FastAPI) endpoints
MCP Server Composition: Integrates with osc-mcp, unity3d-mcp, vrchat-mcp, avatar-mcp, blender-mcp, gimp-mcp
Robot Model Creation: Automated 3D model creation using blender-mcp (geometry) + gimp-mcp (textures)

📚 Documentation

Unity Vbot Instantiation Guide - Complete guide for instantiating virtual robots in Unity3D with proper terminology

🚀 Quick Start

Installation

# Clone repository
git clone https://github.com/sandraschi/robotics-mcp.git
cd robotics-mcp

# Install dependencies
pip install -e ".[dev]"

# Or install from PyPI (when published)
pip install robotics-mcp

Configuration

Create configuration file at ~/.robotics-mcp/config.yaml:

robotics:
  moorebot_scout:
    enabled: false
    robot_id: "scout_01"
    ip_address: "192.168.1.100"
    port: 9090
    mock_mode: true
  virtual:
    enabled: true
    platform: "unity"
    unity:
      host: "localhost"
      port: 8080
  mcp_integration:
    osc_mcp:
      enabled: true
      prefix: "osc"
    unity3d_mcp:
      enabled: true
      prefix: "unity"
    vrchat_mcp:
      enabled: true
      prefix: "vrchat"
    avatar_mcp:
      enabled: true
      prefix: "avatar"
    blender_mcp:
      enabled: true
      prefix: "blender"
    gimp_mcp:
      enabled: true
      prefix: "gimp"
server:
  enable_http: true
  http_port: 8080
  log_level: "INFO"

Running the Server

stdio Mode (MCP Protocol)

python -m robotics_mcp.server --mode stdio

HTTP Mode (FastAPI)

python -m robotics_mcp.server --mode http --port 8080

Dual Mode (Both stdio + HTTP)

python -m robotics_mcp.server --mode dual --port 8080

🛠️ Usage

MCP Tools

Robot Control

# Get robot status
await robot_control(robot_id="scout_01", action="get_status")

# Move robot
await robot_control(
    robot_id="scout_01",
    action="move",
    linear=0.2,
    angular=0.0
)

# Stop robot
await robot_control(robot_id="scout_01", action="stop")

Virtual Robotics

# Spawn virtual robot in Unity
await virtual_robotics(
    robot_type="scout",
    action="spawn_robot",
    platform="unity",
    position={"x": 0, "y": 0, "z": 0}
)

# Load Marble environment
await virtual_robotics(
    action="load_environment",
    environment="stroheckgasse_apartment",
    platform="unity"
)

Robot Model Tools

# Create Scout model from scratch (uses blender-mcp + gimp-mcp)
await robot_model_create(
    robot_type="scout",
    output_path="D:/Models/scout_model.fbx",
    format="fbx",
    dimensions={"length": 0.115, "width": 0.10, "height": 0.08},
    create_textures=True,
    texture_style="realistic"
)

# Import robot model into Unity
await robot_model_import(
    robot_type="scout",
    model_path="D:/Models/scout_model.fbx",
    format="fbx",
    platform="unity",
    project_path="D:/Projects/UnityRobots"
)

# Convert model between formats
await robot_model_convert(
    source_path="D:/Models/scout.fbx",
    source_format="fbx",
    target_format="glb",
    target_path="D:/Models/scout.glb"
)

HTTP API

Health Check

curl http://localhost:8080/api/v1/health

List Robots

curl http://localhost:8080/api/v1/robots

Control Robot

curl -X POST http://localhost:8080/api/v1/robots/scout_01/control \
  -H "Content-Type: application/json" \
  -d '{"action": "move", "linear": 0.2, "angular": 0.0}'

List Tools

curl http://localhost:8080/api/v1/tools

Call Tool

curl -X POST http://localhost:8080/api/v1/tools/robot_control \
  -H "Content-Type: application/json" \
  -d '{"robot_id": "scout_01", "action": "get_status"}'

📚 Documentation

Comprehensive Project Notes 📖 Complete project documentation!
VRM vs Robot Models 🤖 VRM format guide - when to use VRM vs FBX/GLB
Unity Vbot Instantiation Guide 🎮 Complete guide for instantiating virtual robots in Unity3D
Implementation Plan
Quick Start: VRChat ⚡ Get Scout into VRChat!
ROS 1.4 Local Setup 🐳 Full local ROS environment for Scout!
VRChat Integration Guide
VRChat Scout Setup - Complete guide
Architecture
API Reference
MCP Integration

🧪 Testing

# Run all tests
pytest

# Run unit tests only
pytest tests/unit

# Run integration tests
pytest tests/integration

# Run with coverage
pytest --cov=robotics_mcp --cov-report=html

🔧 Development

Project Structure

robotics-mcp/
├── src/robotics_mcp/
│   ├── server.py              # Main FastMCP server
│   ├── clients/               # Robot client implementations
│   ├── integrations/          # MCP server integration wrappers
│   ├── tools/                 # Portmanteau tool implementations
│   └── utils/                 # Utilities (config, state, mock data)
├── tests/
│   ├── unit/                  # Unit tests
│   └── integration/           # Integration tests
├── docs/                      # Documentation
├── scripts/                   # Utility scripts
└── mcpb/                      # MCPB packaging

Code Quality

# Format code
black src/ tests/

# Lint code
ruff check src/ tests/

# Type checking
mypy src/

🤝 Contributing

Contributions welcome! Please see CONTRIBUTING.md for guidelines.

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

FastMCP framework
ROS community
Unity3D, VRChat, World Labs Marble/Chisel
MCP ecosystem contributors

Status: Beta - Virtual robotics (vbot) prioritized, physical robot support coming after hardware arrives (XMas 2025)