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:
- Configuration - Verifies tunnel token and configuration exist
- Local Server - Tests server connectivity on
localhost:8766 - Cloudflared Process - Checks if cloudflared is running
- DNS Resolution - Verifies DNS record exists and resolves correctly
- 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
/sseif/mcpdoesn'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:
- A
pyproject.tomlwith a package name - An
integration.pywith aregister(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.pyexamples 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.
