Skip to content

installation-from-source.md

Latest commit

 

History

History
257 lines (189 loc) · 7.47 KB

installation-from-source.md

File metadata and controls

257 lines (189 loc) · 7.47 KB

Installation from Source

⚠️ Prerequisite: You need either ROS installed locally on your machine OR access over the network to a robot/computer with ROS installed. This MCP server connects to ROS systems on a robot, so a running ROS environment is required.

This guide covers installing the ROS MCP Server from source code. For most users, we recommend using the pip install method instead.

1. Clone the Repository

git clone https://github.com/robotmcp/ros-mcp-server.git

⚠️ WSL Users: Clone the repository in your WSL home directory (e.g., /home/username/) instead of the Windows filesystem mount (e.g., /mnt/c/Users/username/). Using the native Linux filesystem provides better performance and avoids potential permission issues.

Note the absolute path to the cloned directory — you'll need this later when configuring your language model client.

2. Install UV (Python Virtual Environment Manager)

You can install uv using one of the following methods:

Option A: Shell installer 
curl -LsSf https://astral.sh/uv/install.sh | sh
Option B: Using pip 
pip install uv

3. Install Dependencies

Navigate to the cloned repository and install dependencies:

cd ros-mcp-server
uv sync

4. Configure Language Model Client

Any LLM client that supports MCP can be used. We use Claude Desktop for testing and development.

4.1. Download Claude Desktop

Linux (Ubuntu)
MacOS
Windows (Using WSL)

This will have Claude running on Windows and the MCP server running on WSL. We assume that you have cloned the repository and installed UV on your WSL

4.2. Configure Claude Desktop to launch the MCP server

Linux (Ubuntu)
  • Locate and edit the claude_desktop_config.json file:
  • (If the file does not exist, create it)
~/.config/Claude/claude_desktop_config.json
  • Add the following to the "mcpServers" section of the JSON file
  • Make sure to replace <ABSOLUTE_PATH> with the full absolute path to your ros-mcp-server folder (note: ~ for home directory may not work in JSON files):
{
  "mcpServers": {
    "ros-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/<ABSOLUTE_PATH>/ros-mcp-server",
        "run",
        "server.py"
      ]
    }
  }
}
MacOS
  • Locate and edit the claude_desktop_config.json file:
  • (If the file does not exist, create it)
~/Library/Application\ Support/Claude/claude_desktop_config.json
  • Add the following to the "mcpServers" section of the JSON file
  • Make sure to replace <ABSOLUTE_PATH> with the full absolute path to your ros-mcp-server folder (note: ~ for home directory may not work in JSON files):
{
  "mcpServers": {
    "ros-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/<ABSOLUTE_PATH>/ros-mcp-server",
        "run",
        "server.py"
      ]
    }
  }
}
Windows (Using WSL)
  • Locate and edit the claude_desktop_config.json file:
  • (If the file does not exist, create it)
~/.config/Claude/claude_desktop_config.json
  • Add the following to the "mcpServers" section of the JSON file
  • Make sure to replace <ABSOLUTE_PATH> with the full absolute path to your ros-mcp-server folder (note: ~ for home directory may not work in JSON files):
  • Set the full WSL path to your uv installation (e.g., /home/youruser/.local/bin/uv)
  • Use the correct WSL distribution name (e.g., "Ubuntu-22.04")
{
  "mcpServers": {
    "ros-mcp-server": {
      "command": "wsl",
      "args": [
        "-d", "Ubuntu-22.04",
        "/home/<YOUR_USER>/.local/bin/uv",
        "--directory",
        "/<ABSOLUTE_PATH>/ros-mcp-server",
        "run",
        "server.py"
      ]
    }
  }
}

4.3. Alternative Configuration - HTTP Transport

The above configurations sets up the MCP server using the default STDIO transport layer, which launches the server as a plugin automatically on launching Claude.

It is also possible to configure the MCP server using the http transport layer, which configures Claude to connect to the MCP server when it is launched as a standalone application.

For HTTP transport, the configuration is the same across all platforms. First start the MCP server manually:

Linux/macOS/Windows(WSL):

cd /<ABSOLUTE_PATH>/ros-mcp-server
# Using command line arguments (recommended)
uv run server.py --transport streamable-http --host 127.0.0.1 --port 9000

# Or using environment variables (legacy)
export MCP_TRANSPORT=streamable-http
export MCP_HOST=127.0.0.1
export MCP_PORT=9000
uv run server.py

Then configure Claude Desktop to connect to the HTTP server (same for all platforms):

{
  "mcpServers": {
    "ros-mcp-server-http": {
      "name": "ROS-MCP Server (http)",
      "transport": "http",
      "url": "http://127.0.0.1:9000/mcp"
    }
  }
}
Comparison between STDIO and HTTP Transport

STDIO Transport (Default)

  • Best for: Local development, single-user setups
  • Pros: Simple setup, no network configuration needed
  • Cons: MCP server and LLM/MCP client need to be running on the local machine.
  • Use case: Running MCP server directly with your LLM client

HTTP/Streamable-HTTP Transport

  • Best for: Remote access, multiple clients, production deployments
  • Pros: Network accessible, multiple clients can connect
  • Cons: Requires network configuration, MCP server needs to be run independently.
  • Use case: Remote robots, team environments, web-based clients

4.4. Test the connection

  • Launch Claude Desktop and check connection status.
  • The ros-mcp-server should be visible in your list of tools.

Troubleshooting
  • If the ros-mcp-server doesn't appear even after correctly configuring claude_desktop_config.json, try completely shutting down Claude Desktop using the commands below and then restarting it. This could be a Claude Desktop caching issue.
# Completely terminate Claude Desktop processes
pkill -f claude-desktop
# Or alternatively
killall claude-desktop

# Restart Claude Desktop
claude-desktop

Next Steps

Once you have the MCP server installed from source, continue with the remaining setup steps:

  • Install and run rosbridge (on the target robot)
  • Test your connection
  • Troubleshooting (if needed)

For detailed instructions on these steps, see the main installation guide.