RobotMCP Server

A modular Model Context Protocol (MCP) server with automatic submodule integration, OAuth 2.1 authentication, Supabase user management, and Cloudflare tunnel support. Works with ChatGPT and Claude.ai.

Installation

For Users

# Using uv (recommended)
uv tool install robotmcp-server
robotmcp-server

# Using pip
pip install robotmcp-server
robotmcp-server

For Developers

git clone --recursive https://github.com/robotmcp/robotmcp_server.git
cd robotmcp_server

# Using uv (recommended)
uv venv
uv pip install -e .
uv run robotmcp-server

# Using pip
pip install -e .
robotmcp-server

Edit submodule code directly in modules/ — changes take effect immediately.

You can also manage modules with robotmcp-server add/remove/update.

Features

• Submodule Auto-Discovery: Automatically finds and registers MCP tools from git submodules
• Auto-Install Dependencies: Submodule dependencies are installed automatically at startup
• Streamable HTTP Transport: Modern MCP transport at /mcp
• OAuth 2.1: Full flow with PKCE and dynamic client registration
• Cloudflare Tunnel: Secure access via {name}.robotmcp.ai
• Creator-Only Access: Only the server creator can connect
• Optional OAuth: Disable with ENABLE_OAUTH=false
• Secure CLI Login: POST-based credential transfer (not URL params)
• WSL Support: Reliable browser opening with PowerShell fallback

Project Structure

robotmcp_server/
├── main.py                    # FastAPI app entry point
├── cli.py                     # CLI daemon management
├── config.py                  # Config management (~/.robotmcp-server/)
├── setup.py                   # Browser-based login flow
├── submodule_integration.py   # Auto-discover & register submodule tools
├── submodule_deps.py          # Auto-install submodule dependencies
├── logging_config.py          # Logging with Supabase support
├── sse.py                     # Legacy SSE endpoints
├── oauth/                     # OAuth module (optional)
│   ├── endpoints.py           # OAuth routes
│   ├── middleware.py          # Token validation
│   ├── jwt_utils.py           # JWT token generation/validation
│   ├── stores.py              # Session stores
│   └── templates.py           # HTML templates
└── modules/                   # MCP tool modules (git submodules)
    ├── ros-mcp-server/        # ROS integration module
    └── test-mcp-server/       # Test/example module

Cloud Service: CLI login and tunnel creation are handled by robotmcp-cloud at https://app.robotmcp.ai.

See docs/project_plan.md for architecture details.

CLI Commands

Verification Command

The verify command performs comprehensive diagnostics:

robotmcp-server verify

Checks performed:

1. Configuration - Verifies tunnel token and configuration exist
2. Local Server - Tests server connectivity on localhost:8766
3. Cloudflared Process - Checks if cloudflared is running
4. DNS Resolution - Verifies DNS record exists and resolves correctly
5. Tunnel Endpoints - Tests endpoints through the tunnel (/, /health)

Output includes:

• ✓/✗ status for each check
• Detailed error messages with actionable fixes
• Summary with pass/fail statistics
• Next steps if issues are found

Use this command to diagnose connectivity issues, verify DNS configuration, and ensure your tunnel is working correctly.

Environment Variables

API Endpoints

Connecting MCP Clients

Two endpoints are available:

Client Compatibility:

• Claude.ai: Works with /mcp (recommended)
• ChatGPT: Works with /mcp (recommended)
• Legacy clients: Use /sse if /mcp doesn't work

Example URL:

https://{your-name}.robotmcp.ai/mcp

See docs/workflow.md for connection flow diagrams.

Adding MCP Submodules

The server automatically discovers and integrates MCP tools from git submodules:

# Add a module using the CLI
robotmcp-server add https://github.com/example/my-mcp-tools.git

# Or add tracking a specific branch
robotmcp-server add -b develop https://github.com/example/my-mcp-tools.git

# List installed modules and their compatibility status
robotmcp-server list

# List all available tools
robotmcp-server list-tools

# Update all modules to latest
robotmcp-server update

# Remove a module
robotmcp-server remove my-mcp-tools

Your submodule needs:

1. A pyproject.toml with a package name
2. An integration.py with a register(mcp, **kwargs) function

Compatibility: Modules without an integration module will show as "not compatible" in list and list-tools commands. The server checks for compatibility at startup and warns about incompatible modules.

# my_mcp_tools/integration.py
from fastmcp import FastMCP

def register(mcp: FastMCP, **kwargs) -> None:
    @mcp.tool()
    def my_tool(param: str) -> str:
        """Process a parameter."""
        return f"Result: {param}"

See docs/submodule-integration.md for the complete guide including:

• Full integration.py examples with configuration
• How to organize tools, resources, and prompts
• Environment variable configuration
• Testing your submodule

Documentation

• Installation Guide - Setup, troubleshooting, CLI reference
• Submodule Integration - Creating MCP submodules with integration.py
• Project Plan - Architecture, version history
• Workflow - Flow diagrams, components

Changelog

See CHANGELOG.md for version history.

License

Copyright (c) 2025 Contoro. All rights reserved.

This software is proprietary and confidential. Unauthorized copying, modification, distribution, or use of this software is strictly prohibited without express written permission.