Getting Started

This guide covers installing and running the RobotMCP Server on your machine.

Prerequisites

• Python 3.10+ — check with python --version
• Git — for cloning the repository

Installation

Option 1: pipx (quick start)

pipx install git+https://github.com/robotmcp/robotmcp_server.git

This is the fastest way to get running. Modules (like ROS-MCP) are automatically downloaded on first run.

caution

With a pipx install, you cannot add or remove modules using robotmcp-server add/remove. Use Option 2 if you need to manage modules.

Option 2: Clone and editable install (recommended)

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

An editable install (-e) lets you add, remove, and update modules:

robotmcp-server add https://github.com/example/my-mcp-module.git
robotmcp-server remove my-mcp-module
robotmcp-server update

First Run

robotmcp-server

On first run, the CLI will:

1. Open your browser for login/signup
2. Prompt you for a robot name (e.g., myrobot)
3. Auto-download cloudflared if not already installed
4. Create a Cloudflare tunnel at https://myrobot.robotmcp.ai
5. Start the MCP server in the background

You'll see output like:

==================================================
  RobotMCP Server v2.1.0
==================================================
  User:   [email protected]
  MCP:    https://myrobot.robotmcp.ai/mcp
==================================================
  Copy the MCP URL above to your MCP client
  (ChatGPT, Claude, etc.)

  Server running in background.
  Run 'robotmcp-server stop' to stop.
==================================================

Verify the setup

robotmcp-server verify

This runs comprehensive diagnostics: configuration, local server connectivity, tunnel authentication, DNS resolution, and endpoint reachability.

Manage from the dashboard

Once your server is running, the RobotMCP dashboard is where you share access with teammates, manage your tunnels, and configure servers.

Open Dashboard →

Connecting an LLM

Once your server is running, connect it to any MCP-compatible LLM client.

Claude.ai

1. Add as an MCP integration
2. Enter endpoint: https://your-robot.robotmcp.ai/mcp
3. Complete the OAuth flow when prompted

ChatGPT

1. Go to Settings > Connectors > Add
2. Enter MCP Server URL: https://your-robot.robotmcp.ai/mcp
3. Select OAuth authentication and log in

info

Only the server creator can connect. Other accounts will receive a 403 Forbidden error. To share access, use the server sharing feature on the dashboard.

Managing Modules

Modules add capabilities to your server. The ROS-MCP module comes included by default.

note

Module management (add, remove, update) requires an editable install (Option 2). With a pipx install, you can list modules and tools but cannot modify them.

# List installed modules and their status
robotmcp-server list

# List all available tools across modules
robotmcp-server list-tools

# Add a new module
robotmcp-server add https://github.com/example/my-mcp-module.git

# Update all modules to latest
robotmcp-server update

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

CLI Reference

Command	Description
robotmcp-server	Start server in background
robotmcp-server stop	Stop server and tunnel
robotmcp-server status	Show current status
robotmcp-server verify	Run comprehensive diagnostics
robotmcp-server list	List installed modules with compatibility status
robotmcp-server list-tools	List all available MCP tools
robotmcp-server add <url>	Add a module
robotmcp-server remove <name>	Remove a module
robotmcp-server update	Update all modules to latest
robotmcp-server logout	Clear credentials and stop

Logs are written to ~/.robotmcp-server/server.log.

Updating

pipx install:

pipx uninstall robotmcp-server
pipx install git+https://github.com/robotmcp/robotmcp_server.git

Editable install:

cd robotmcp_server
git pull --recurse-submodules
pip install -e .
robotmcp-server stop && robotmcp-server

Uninstalling

pipx install:

robotmcp-server stop
pipx uninstall robotmcp-server
rm -rf ~/.robotmcp-server  # Remove config (optional)

Editable install:

robotmcp-server stop
pip uninstall robotmcp-server
rm -rf ~/.robotmcp-server  # Remove config (optional)

Troubleshooting

Port 8766 already in use

The CLI automatically cleans up old processes. If issues persist:

robotmcp-server stop

# Or manually
lsof -i :8766        # Find the process
kill <pid>           # Stop it

Server not accessible via tunnel

1. Run robotmcp-server verify to identify the issue
2. Check that cloudflared is installed: cloudflared --version
3. Try restarting: robotmcp-server stop && robotmcp-server

OAuth login issues

robotmcp-server logout    # Clear credentials
robotmcp-server           # Start fresh

WSL users

The CLI automatically detects WSL and uses PowerShell to open the browser for authentication. No extra configuration needed.