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

Command	Description
`robotmcp-server`	Start server in background
`robotmcp-server stop`	Stop server and tunnel
`robotmcp-server status`	Show current status
`robotmcp-server verify`	Comprehensive verification (server, tunnel, DNS, connectivity)
`robotmcp-server list`	List installed MCP server modules with compatibility status
`robotmcp-server list-tools`	List all available MCP tools from compatible modules
`robotmcp-server add <url>`	Add an MCP server module (git submodule)
`robotmcp-server remove <name>`	Remove an MCP server module
`robotmcp-server update`	Update all MCP server modules to latest
`robotmcp-server logout`	Clear credentials and stop

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

Variable	Description
`SUPABASE_URL`	Supabase project URL
`SUPABASE_ANON_KEY`	Supabase anonymous key
`SUPABASE_JWT_SECRET`	JWT secret for token validation
`ENABLE_OAUTH`	Set `false` to disable OAuth (default: `true`)
`ROBOTMCP_CLOUD_URL`	Cloud service URL (default: `https://app.robotmcp.ai`)

API Endpoints

Endpoint	Description
`GET /`	Server info
`POST /mcp`	Streamable HTTP transport (recommended)
`GET /sse`	Legacy SSE (backward compat)
`/.well-known/oauth-authorization-server`	OAuth metadata

Connecting MCP Clients

Two endpoints are available:

Endpoint	Transport	Usage
`/mcp`	Streamable HTTP	Try first (recommended)
`/sse`	Legacy SSE	Use if /mcp doesn't work

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:

A pyproject.toml with a package name
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

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