GS Robot MCP Server

🤖 Gausium OpenAPI MCP Server

🔧 A powerful MCP server bridging AI models with Gausium robots

Control and monitor Gausium cleaning robots through Claude, Cursor, and other AI assistants

🚀 Quick Start • 📖 Documentation • 🛠️ Installation • 🎯 Examples • 🇨🇳 中文文档

🌟 What is this?

This MCP (Model Control Protocol) server enables seamless interaction between AI models and Gausium cleaning robots through a standardized interface. Perfect for building intelligent automation workflows with Claude Code, Cursor, and other MCP-compatible AI tools.

🔗 Repository: https://github.com/cfrs2005/mcp-gs-robot

🎯 Key Benefits

🤖 AI-First Design: Built specifically for AI assistant integration
🔄 Real-time Control: Monitor and command robots instantly
📊 Rich Data Access: Get detailed status, maps, and task reports
🛡️ Secure: OAuth-based authentication with environment variables
🌐 Universal: Works with Claude, Cursor, and any MCP client

🏗️ Architecture

The server follows a layered architecture that separates concerns and promotes maintainability:

Architecture Diagram

🔄 MCP Protocol Flow

The diagram below shows how AI models interact with Gausium robots through the MCP protocol:

MCP Protocol Flow

✨ Features

🛠️ Core MCP Tools

Tool	Description	Status
🤖 `list_robots`	List all accessible robots	✅ Ready
📊 `get_robot_status`	Get detailed robot status and position	✅ Ready
📋 `list_robot_task_reports`	Retrieve cleaning task reports with filtering	✅ Ready
🗺️ `list_robot_maps`	Get available maps for robot navigation	✅ Ready
🎯 `create_robot_command`	Send commands to robots (start/pause/stop)	✅ Ready
🏢 `get_site_info`	Get building and floor information	✅ Ready
📍 `get_map_subareas`	Get detailed area information for tasks	✅ Ready
🚀 `submit_temp_task`	Submit temporary cleaning tasks	✅ Ready

🧠 Smart Routing Tools (Enhanced in v0.1.12)

Tool	Description	Status
🎯 `get_robot_status_smart`	Auto-select V1/V2 API based on robot series	✅ Ready
📊 `get_task_reports_smart`	Intelligent task report API routing	✅ Ready
🔍 `get_robot_capabilities`	Show supported APIs for specific robot	✅ Ready

🔧 Advanced Workflows

🎛️ Automated Task Execution: Complete workflows from status → task selection → execution
📈 Batch Operations: Handle multiple robots simultaneously
🗺️ Map Management: Upload, download, and manage robot maps
📊 Report Generation: Generate PNG maps from task reports
🏗️ Site-based Tasks: Advanced task creation with building/floor context

🤝 Supported Robot Lines

M-line Robots (Traditional Cleaning Robots)

OMNIE (OMNIE series) - Multi-purpose cleaning robot
Vacuum 40 (40 series) - Vacuum cleaning robot
Scrubber 50 (50 series) - Floor scrubbing robot
Scrubber 75 (75 series) - Heavy-duty floor scrubbing robot

S-line Robots (Advanced Smart Robots, including SW series)

Phantas (S series) - Phantom intelligent cleaning robot
BEETLE (SW series) - Beetle smart cleaning robot

📁 Project Structure

The project follows a structured layout optimized for MCP development:

🗂️ mcp-gs-robot/
├── 📦 src/gs_openapi/           # Main package
│   ├── 🔌 api/                  # Direct API integrations
│   │   ├── 🤖 robots.py         # Robot management APIs
│   │   └── 🗺️ maps.py           # Map management APIs
│   ├── 🔐 auth/                 # Authentication layer
│   │   └── 🎫 token_manager.py  # OAuth token lifecycle
│   ├── ⚙️ config.py             # Configuration management
│   ├── 🔧 core/                 # Core functionality
│   │   ├── 📡 client.py         # HTTP client wrapper
│   │   └── 🛣️ endpoints.py      # API endpoint definitions
│   ├── 🔌 mcp/                  # MCP server implementation
│   │   └── 🌉 gausium_mcp.py    # Main MCP bridge
│   └── 🔄 workflows/            # Automated workflows
│       └── 🎯 task_engine.py    # Task automation engine
├── 📚 docs/                     # Documentation
│   ├── 🖼️ images/               # Visual documentation
│   ├── 📖 apis.md              # API documentation
│   └── 🧪 TESTING_GUIDE.md     # Testing instructions
├── 🚀 main.py                  # Application entry point
└── 📋 pyproject.toml           # Package configuration

🔍 Key Components

Component	Purpose	Icon
config.py	Base URLs, API paths, environment variables	⚙️
token_manager.py	OAuth token acquisition and refresh	🔐
api/robots.py	Robot status, commands, task reports	🤖
api/maps.py	Map listing, upload, download	🗺️
gausium_mcp.py	MCP server integration layer	🌉
task_engine.py	Automated workflow orchestration	🎯
main.py	Server initialization and tool registration	🚀

🚀 Quick Start

📦 Installation

Option 1: Install from PyPI (Recommended)

pip install mcp-gs-robot

Option 2: Install from Source

# Clone repository
git clone https://github.com/cfrs2005/mcp-gs-robot.git
cd mcp-gs-robot

# Setup with uv (recommended)
uv venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
uv pip install -e .

🔧 Configuration

Set up your Gausium API credentials:

# Required environment variables
export GS_CLIENT_ID="your_client_id"
export GS_CLIENT_SECRET="your_client_secret" 
export GS_OPEN_ACCESS_KEY="your_access_key"

🔑 Get credentials from Gausium Developer Portal

🏃‍♂️ Running the Server

# Start MCP server (stdio mode)
python -m gs_openapi.main
# or if installed via pip:
mcp-gs-robot

✅ Server starts using stdio transport (perfect for Claude Code)

🔌 Claude Code Integration

Method 1: Automatic installation with environment setup

# Add MCP server with environment variables
claude mcp add mcp-gs-robot \
  --env GS_CLIENT_ID="your_client_id" \
  --env GS_CLIENT_SECRET="your_client_secret" \
  --env GS_OPEN_ACCESS_KEY="your_access_key"

Method 2: Manual configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-gs-robot": {
      "command": "mcp-gs-robot",
      "env": {
        "GS_CLIENT_ID": "your_client_id",
        "GS_CLIENT_SECRET": "your_client_secret", 
        "GS_OPEN_ACCESS_KEY": "your_access_key"
      }
    }
  }
}

Method 3: Using environment file

If you prefer to use a .env file:

# Set global environment variables
export GS_CLIENT_ID="your_client_id"
export GS_CLIENT_SECRET="your_client_secret"
export GS_OPEN_ACCESS_KEY="your_access_key"

# Simple MCP installation
claude mcp add mcp-gs-robot

💡 Note: This MCP server uses stdio transport (not SSE), which is perfect for Claude Code integration

🎯 Examples

📱 Claude Code Usage

# In Claude Code, you can now use natural language:

"List all my robots"
# → Calls mcp__mcp-gs-robot__list_robots

"Get status of robot GS101-0100-V1P-B001" 
# → Calls mcp__mcp-gs-robot__get_robot_status

"Start cleaning task for robot in building 5"
# → Orchestrates site info → map selection → task creation

🖥️ IDE Integration

Cursor Configuration:

Cursor Usage Screenshot

Cherry Studio Configuration:

Cherry Studio Configuration

🐛 Debugging

Monitor server logs for troubleshooting:

MCP Debug Screenshot

📖 Documentation

Document	Purpose
🎯 Claude Code Integration	Complete Claude Code setup guide
📋 API Reference	Complete API documentation
🧪 Testing Guide	How to test the MCP server
🔧 Configuration	Detailed setup instructions

🤝 Contributing

We welcome contributions! Please:

🍴 Fork the repository
🌿 Create a feature branch
✅ Add tests for your changes
📝 Update documentation
🔄 Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🆘 Support

Made with ❤️ for the Claude Code community

Enabling AI-powered robot automation, one task at a time 🤖✨

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

A Model Control Protocol plugin for controlling GS cleaning robots, supporting robot listing, status monitoring, navigation commands, task execution, and remote control operations.

Related MCP Servers

Ecovacs MCP Serverofficial
ecovacs-ai
A
security
A
license
A
quality
A control server that enables AI assistants to interact with Ecovacs robot vacuums through MCP protocol, supporting device listing, cleaning control, charging control, and status queries.
Last updated -
4
16
MIT License
ROS2 MCP Server
kakimochi
-
security
F
license
-
quality
A Python-based server that enables AI assistants to control robots by integrating the Model Context Protocol (MCP) with ROS 2, allowing for natural language commands that translate into robot movement via the /cmd\_vel topic.
Last updated -
61
nUR MCP Server
nonead
A
security
F
license
A
quality
A Model Context Protocol server that enables natural language interactive control of Universal Robots collaborative robots, allowing users to control robot motion, monitor status, and execute programs through direct commands to large language models.
Last updated -
29
3
MCP with Gemini Integration
ImDPS
-
security
F
license
-
quality
Implements a Model Control Protocol server integrated with Google Gemini LLM, providing a flexible framework for building AI-powered applications.
Last updated -

View all related MCP servers