From fb63ef2f8958831d99c65d6b77c5bac3b57354c2 Mon Sep 17 00:00:00 2001 From: Rohit John Varghese Date: Sat, 25 Oct 2025 23:39:18 -0500 Subject: [PATCH 1/6] Update installation documentation for pip install support - Replace cloning/UV setup with pipx as primary installation method - Add pip as alternative installation option - Update MCP client configurations to use ros-mcp command - Simplify JSON configurations for all platforms (Ubuntu, macOS, WSL) - Create separate installation-from-source.md for developers - Remove duplicate content and link back to main guide - Update HTTP transport commands to use ros-mcp - Improve documentation structure and user experience --- docs/installation-from-source.md | 257 +++++++++++++++++++++++++++++++ docs/installation.md | 90 +++++------ 2 files changed, 295 insertions(+), 52 deletions(-) create mode 100644 docs/installation-from-source.md diff --git a/docs/installation-from-source.md b/docs/installation-from-source.md new file mode 100644 index 0000000..f62cdfd --- /dev/null +++ b/docs/installation-from-source.md @@ -0,0 +1,257 @@ +# 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](installation.md) instead. + +## 1. Clone the Repository + +```bash +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`](https://github.com/astral-sh/uv) using one of the following methods: + +
+Option A: Shell installer + +```bash +curl -LsSf https://astral.sh/uv/install.sh | sh +``` + +
+ +
+Option B: Using pip + +```bash +pip install uv +``` + +
+ +## 3. Install Dependencies + +Navigate to the cloned repository and install dependencies: + +```bash +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) + +- Follow the installation instructions from the community-supported [claude-desktop-debian](https://github.com/aaddrick/claude-desktop-debian) + +
+ +
+MacOS + +- Download from [claude.ai](https://claude.ai/download) + +
+ +
+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](https://apps.microsoft.com/detail/9pn20msr04dw?hl=en-US&gl=US) + +- Download from [claude.ai](https://claude.ai/download) + +
+ +### 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) +```bash +~/.config/Claude/claude_desktop_config.json +``` + +- Add the following to the `"mcpServers"` section of the JSON file +- Make sure to replace `` with the **full absolute path** to your `ros-mcp-server` folder (note: `~` for home directory may not work in JSON files): + +```json +{ + "mcpServers": { + "ros-mcp-server": { + "command": "uv", + "args": [ + "--directory", + "//ros-mcp-server", + "run", + "server.py" + ] + } + } +} +``` + +
+ +
+MacOS + +- Locate and edit the `claude_desktop_config.json` file: +- (If the file does not exist, create it) +```bash +~/Library/Application\ Support/Claude/claude_desktop_config.json +``` + +- Add the following to the `"mcpServers"` section of the JSON file +- Make sure to replace `` with the **full absolute path** to your `ros-mcp-server` folder (note: `~` for home directory may not work in JSON files): + +```json +{ + "mcpServers": { + "ros-mcp-server": { + "command": "uv", + "args": [ + "--directory", + "//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) +```bash +~/.config/Claude/claude_desktop_config.json +``` + +- Add the following to the `"mcpServers"` section of the JSON file +- Make sure to replace `` 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"`) + +```json +{ + "mcpServers": { + "ros-mcp-server": { + "command": "wsl", + "args": [ + "-d", "Ubuntu-22.04", + "/home//.local/bin/uv", + "--directory", + "//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):** +```bash +cd //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): + +```json +{ + "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. +```bash +# 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](installation.md#3-install-and-run-rosbridge-on-the-target-robot-where-ros-will-be-running). diff --git a/docs/installation.md b/docs/installation.md index a456d15..08de3a1 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -3,9 +3,7 @@ > ⚠️ **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. Installation includes the following steps: -- Install the MCP server - - Clone this repository - - Install uv (Python virtual environment manager) +- Install the MCP server using pip - Install and configure the Language Model Client - Install any language model client (We demonstrate with Claude Desktop) - Configure the client to run the MCP server and connect automatically on launch. @@ -17,38 +15,35 @@ Below are detailed instructions for each of these steps. --- # 1. Install the MCP server (On the host machine where the LLM will be running) -## 1.1. Clone the Repository +Install using pipx (recommended for isolated installation): ```bash -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. - ---- - -## 1.2. Install UV (Python Virtual Environment Manager) - -You can install [`uv`](https://github.com/astral-sh/uv) using one of the following methods: - -
-Option A: Shell installer +# Install pipx if you don't have it +pip install pipx -```bash -curl -LsSf https://astral.sh/uv/install.sh | sh +# Install ros-mcp using pipx +pipx install ros-mcp ``` -
+**Benefits of pipx:** +- Isolated installation in its own virtual environment +- Won't conflict with other Python packages +- Easy to uninstall: `pipx uninstall ros-mcp` +- Automatic PATH management
-Option B: Using pip +Alternative Installation Options + +### Option A: Install using pip +For users who prefer traditional pip installation: ```bash -pip install uv +pip install ros-mcp ``` +### Option B: Install from Source +For developers or advanced users who need to modify the source code, see [Installation from Source](installation-from-source.md). +
--- @@ -94,19 +89,16 @@ This will have Claude running on Windows and the MCP server running on WSL. We a ~/.config/Claude/claude_desktop_config.json ``` -- Add the following to the `"mcpServers"` section of the JSON file -- Make sure to replace `` with the **full absolute path** to your `ros-mcp-server` folder (note: `~` for home directory may not work in JSON files): +- Add the following to the `"mcpServers"` section of the JSON file: ```json { "mcpServers": { "ros-mcp-server": { - "command": "uv", + "command": "bash", "args": [ - "--directory", - "//ros-mcp-server", - "run", - "server.py" + "-lc", + "ros-mcp --transport=stdio" ] } } @@ -125,19 +117,16 @@ This will have Claude running on Windows and the MCP server running on WSL. We a ~/Library/Application\ Support/Claude/claude_desktop_config.json ``` -- Add the following to the `"mcpServers"` section of the JSON file -- Make sure to replace `` with the **full absolute path** to your `ros-mcp-server` folder (note: `~` for home directory may not work in JSON files): +- Add the following to the `"mcpServers"` section of the JSON file: ```json { - "mcpServers": { + "mcpServers":{ "ros-mcp-server": { - "command": "uv", + "command": "zsh", "args": [ - "--directory", - "//ros-mcp-server", - "run", - "server.py" + "-lc", + "ros-mcp --transport=stdio" ] } } @@ -156,24 +145,21 @@ This will have Claude running on Windows and the MCP server running on WSL. We a ~/.config/Claude/claude_desktop_config.json ``` -- Add the following to the `"mcpServers"` section of the JSON file -- Make sure to replace `` 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`) +- Add the following to the `"mcpServers"` section of the JSON file: - Use the correct **WSL distribution name** (e.g., `"Ubuntu-22.04"`) ```json { - "mcpServers": { + "mcpServers":{ "ros-mcp-server": { "command": "wsl", - "args": [ - "-d", "Ubuntu-22.04", - "/home//.local/bin/uv", - "--directory", - "//ros-mcp-server", - "run", - "server.py" - ] + "args": [ + "-d", + "Ubuntu-22.04", + "bash", + "-lc", + "ros-mcp --transport=stdio" + ] } } } @@ -196,7 +182,7 @@ For HTTP transport, the configuration is the same across all platforms. First st ```bash cd //ros-mcp-server # Using command line arguments (recommended) -uv run server.py --transport streamable-http --host 127.0.0.1 --port 9000 +ros-mcp --transport streamable-http --host 127.0.0.1 --port 9000 # Or using environment variables (legacy) export MCP_TRANSPORT=streamable-http From 80e05120cf54146d4eb60f352a9010efc6939d7f Mon Sep 17 00:00:00 2001 From: Rohit John Varghese Date: Sat, 25 Oct 2025 23:47:46 -0500 Subject: [PATCH 2/6] Move pipx benefits into advanced dropdown for cleaner main flow --- docs/installation.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index 08de3a1..ebf0b16 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -25,12 +25,6 @@ pip install pipx pipx install ros-mcp ``` -**Benefits of pipx:** -- Isolated installation in its own virtual environment -- Won't conflict with other Python packages -- Easy to uninstall: `pipx uninstall ros-mcp` -- Automatic PATH management -
Alternative Installation Options @@ -44,6 +38,13 @@ pip install ros-mcp ### Option B: Install from Source For developers or advanced users who need to modify the source code, see [Installation from Source](installation-from-source.md). +### Why pipx? +**Benefits of pipx:** +- Isolated installation in its own virtual environment +- Won't conflict with other Python packages +- Easy to uninstall: `pipx uninstall ros-mcp` +- Automatic PATH management +
--- From c8a0147f17c8bf37940ad6a1e6a036528dbca675 Mon Sep 17 00:00:00 2001 From: Rohit John Varghese Date: Sun, 26 Oct 2025 16:10:39 -0500 Subject: [PATCH 3/6] Improve installation documentation based on reviewer feedback - Fix debug commands in 6.2 to use ros-mcp instead of uv run server.py for pipx installation consistency - Remove collapsible sections in section 5 to improve visibility of LLM client options - Move 'If you're still having issues' from 6.3 into 6.1 for better organization - Split debug commands into separate, organized code blocks - Wrap debug commands and 'Why pipx?' sections in collapsible details blocks - Update section numbering and structure for better navigation --- docs/installation.md | 85 ++++++++++++++++++++++++-------------------- 1 file changed, 47 insertions(+), 38 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index ebf0b16..b0a9717 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -17,6 +17,17 @@ Below are detailed instructions for each of these steps. Install using pipx (recommended for isolated installation): +
+Why pipx? + +**Benefits of pipx:** +- Isolated installation in its own virtual environment +- Won't conflict with other Python packages +- Easy to uninstall: `pipx uninstall ros-mcp` +- Automatic PATH management + +
+ ```bash # Install pipx if you don't have it pip install pipx @@ -38,12 +49,6 @@ pip install ros-mcp ### Option B: Install from Source For developers or advanced users who need to modify the source code, see [Installation from Source](installation-from-source.md). -### Why pipx? -**Benefits of pipx:** -- Isolated installation in its own virtual environment -- Won't conflict with other Python packages -- Easy to uninstall: `pipx uninstall ros-mcp` -- Automatic PATH management @@ -368,23 +373,22 @@ What topics and services do you see on the robot? # 5. Alternate Clients (ChatGPT, Gemini, Cursor) -
- Examples and setup instructions for other LLMs +Examples and setup instructions for other LLMs -#### 3.2.1. Cursor IDE +## 5.1. Cursor IDE For detailed Cursor setup instructions, see our [Cursor Tutorial](../examples/7_cursor/README.md). -#### 3.2.2. ChatGPT +## 5.2. ChatGPT For detailed ChatGPT setup instructions, see our [ChatGPT Tutorial](../examples/6_chatgpt/README.md). -#### 3.2.3. Google Gemini +## 5.3. Google Gemini For detailed Gemini setup instructions, see our [Gemini Tutorial](../examples/2_gemini/README.md). -
-Custom MCP Client +## 5.4. Custom MCP Client +You can also use the MCP server directly in your Python code. Here's an example of how to integrate it programmatically: -#### 3.2.1. Using the MCP Server Programmatically -You can also use the MCP server directly in your Python code: +
+Python Integration Example ```python from mcp import ClientSession, StdioServerParameters @@ -405,8 +409,6 @@ async def main():
-
- --- @@ -504,39 +506,46 @@ curl http://localhost:9000
-## 6.2. Debug Commands +
+If you're still having issues: +1. **Check the logs**: Look for error messages in your LLM client and MCP server logs +2. **Test with turtlesim**: Try the [turtlesim tutorial](../examples/1_turtlesim/README.md) to verify basic functionality +3. **Open an issue**: Create an issue on the [GitHub repository](https://github.com/robotmcp/ros-mcp-server/issues) with: + - Your operating system + - ROS version + - LLM client being used + - Error messages + - Steps to reproduce + +
+ +
+6.2. Debug Commands + +### Test ROS connectivity ```bash -# Test ROS connectivity ros2 topic list # For ROS 2 rostopic list # For ROS 1 +``` -# Test rosbridge +### Test rosbridge +```bash curl -I http://localhost:9090 +``` -# Test MCP server manually -cd //ros-mcp-server -uv run server.py +### Test MCP server manually +```bash +ros-mcp --transport=stdio +``` -# Check processes +### Check running processes +```bash ps aux | grep rosbridge ps aux | grep ros-mcp ``` -## 6.3. Getting Help - -
-If you're still having issues: - +
-1. **Check the logs**: Look for error messages in your LLM client and MCP server logs -2. **Test with turtlesim**: Try the [turtlesim tutorial](../examples/1_turtlesim/README.md) to verify basic functionality -3. **Open an issue**: Create an issue on the [GitHub repository](https://github.com/robotmcp/ros-mcp-server/issues) with: - - Your operating system - - ROS version - - LLM client being used - - Error messages - - Steps to reproduce -
--- \ No newline at end of file From c9dbd7be094cb5ef231013acd3acc7d574bf010e Mon Sep 17 00:00:00 2001 From: Rohit John Varghese Date: Sun, 26 Oct 2025 16:21:46 -0500 Subject: [PATCH 4/6] Further improve installation documentation organization - Move installation commands before 'Why pipx?' section for better flow - Wrap section 5 (Alternate Clients) in collapsible details block - Add descriptive text to section 6.1 Common Issues - Convert debug command headings to plain text for cleaner appearance - Improve overall document structure and readability --- docs/installation.md | 43 +++++++++++++++++++++++++------------------ 1 file changed, 25 insertions(+), 18 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index b0a9717..2adb9af 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -17,6 +17,13 @@ Below are detailed instructions for each of these steps. Install using pipx (recommended for isolated installation): +```bash +# Install pipx if you don't have it +pip install pipx + +# Install ros-mcp using pipx +pipx install ros-mcp +```
Why pipx? @@ -28,14 +35,6 @@ Install using pipx (recommended for isolated installation):
-```bash -# Install pipx if you don't have it -pip install pipx - -# Install ros-mcp using pipx -pipx install ros-mcp -``` -
Alternative Installation Options @@ -372,8 +371,8 @@ What topics and services do you see on the robot? --- # 5. Alternate Clients (ChatGPT, Gemini, Cursor) - -Examples and setup instructions for other LLMs +
+Examples and setup instructions for other LLM Hosts and Clients ## 5.1. Cursor IDE For detailed Cursor setup instructions, see our [Cursor Tutorial](../examples/7_cursor/README.md). @@ -385,10 +384,9 @@ For detailed ChatGPT setup instructions, see our [ChatGPT Tutorial](../examples/ For detailed Gemini setup instructions, see our [Gemini Tutorial](../examples/2_gemini/README.md). ## 5.4. Custom MCP Client -You can also use the MCP server directly in your Python code. Here's an example of how to integrate it programmatically: - +You can also use the MCP server directly in your Python code.
-Python Integration Example +Here is a python example of how to integrate it programmatically ```python from mcp import ClientSession, StdioServerParameters @@ -409,12 +407,17 @@ async def main():
+
+ --- # 6. Troubleshooting -## 6.1. Common Issues +
+6.1. Common Issues + +Here are some frequently encountered issues and their solutions:
MCP Server Not Appearing in Client @@ -520,26 +523,30 @@ curl http://localhost:9000
+--- + +
+
6.2. Debug Commands -### Test ROS connectivity +Test ROS connectivity ```bash ros2 topic list # For ROS 2 rostopic list # For ROS 1 ``` -### Test rosbridge +Test rosbridge ```bash curl -I http://localhost:9090 ``` -### Test MCP server manually +Test MCP server manually ```bash ros-mcp --transport=stdio ``` -### Check running processes +Check running processes ```bash ps aux | grep rosbridge ps aux | grep ros-mcp From 0b9226b6609b89ed05f32f97f9aeef1e5d2198d6 Mon Sep 17 00:00:00 2001 From: Rohit John Varghese Date: Mon, 27 Oct 2025 14:51:04 -0500 Subject: [PATCH 5/6] Add Option C: Install from source using pipx - Add new installation option for developers who want source access with pipx isolation - Include step-by-step commands to clone repository and install with pipx install . - Add note that regular pip install . also works for source installation - Provide more flexibility for different developer preferences and environments --- docs/installation.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/installation.md b/docs/installation.md index 2adb9af..d4a7b48 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -48,8 +48,19 @@ pip install ros-mcp ### Option B: Install from Source For developers or advanced users who need to modify the source code, see [Installation from Source](installation-from-source.md). +### Option C: Install from Source using pipx +For developers who want to install from source but still use pipx for isolation: -
+```bash +# Clone the repository +git clone https://github.com/robotmcp/ros-mcp-server.git +cd ros-mcp-server + +# Install from source using pipx +pipx install . +``` + +> **Note**: This also works with regular pip: `pip install .` --- From 856b4feb02cb8e3a0cc817a204fcf46a0c21e374 Mon Sep 17 00:00:00 2001 From: Rohit John Varghese Date: Mon, 27 Oct 2025 14:52:36 -0500 Subject: [PATCH 6/6] Update installation documentation - Additional improvements to installation guide structure and content --- docs/installation.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/installation.md b/docs/installation.md index d4a7b48..762c933 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -62,6 +62,8 @@ pipx install . > **Note**: This also works with regular pip: `pip install .` +
+ --- # 2. Install and configure a Language Model Client