# ROS1 Noetic MCP Server

An MCP (Model Context Protocol) server that provides LLM access to ROS1 Noetic robotic systems. Built with [FastMCP](https://gofastmcp.com) and deployed as a Docker container.

## Claude Code Quick Start

Add ROS MCP to Claude Code with a single command:

```bash
claude mcp add ros \
  -e ROS_MASTER_URI=http://localhost:11311 \
  -- docker run -i --rm --network host \
  -e ROS_MASTER_URI \
  ghcr.io/lopisan/ros-mcp --transport stdio
```

For remote ROS master:

```bash
claude mcp add ros \
  -e ROS_MASTER_URI=http://192.168.1.100:11311 \
  -e ROS_IP=192.168.1.50 \
  -- docker run -i --rm --network host \
  -e ROS_MASTER_URI -e ROS_IP \
  ghcr.io/lopisan/ros-mcp --transport stdio
```

## Features

- **Topic Management**: List, publish, subscribe, and echo ROS topics
- **Service Management**: List and call ROS services
- **Parameter Management**: Get, set, list, and delete ROS parameters
- **Node Inspection**: List nodes and get detailed node information
- **TF Transforms**: Query coordinate frame transforms, transform points/poses
- **Message Introspection**: View message and service definitions

## Quick Start

### Prerequisites

- Docker and Docker Compose
- Running ROS1 Noetic system with roscore

### Running with Docker Compose

1. Clone this repository:
```bash
git clone <repository-url>
cd ros_mcp
```

2. Set environment variables (optional):
```bash
export ROS_MASTER_URI=http://localhost:11311
export ROS_IP=127.0.0.1
```

3. Start the MCP server:
```bash
docker compose up -d
```

The server will be available at `http://localhost:8000/mcp`.

### Running with stdio transport (for local development)

```bash
docker compose --profile stdio up ros-mcp-server-stdio
```

## Testing the Server

### Using MCP Inspector

The easiest way to test the MCP server is using the official MCP Inspector:

```bash
npx @modelcontextprotocol/inspector http://localhost:8000/mcp
```

This opens an interactive web UI where you can:
- Browse available tools and resources
- Test tool calls with custom parameters
- View server responses in real-time

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `ROS_MASTER_URI` | `http://localhost:11311` | URI of the ROS master |
| `ROS_IP` | `127.0.0.1` | IP address of this machine for ROS networking |
| `MCP_TRANSPORT` | `http` | Transport mode: `http`, `sse`, or `stdio` |
| `MCP_PORT` | `8000` | Port for HTTP transport |

### MCP Client Configuration

Add to your MCP client configuration (e.g., Claude Desktop):

```json
{
  "mcpServers": {
    "ros": {
      "url": "http://localhost:8000/mcp"
    }
  }
}
```

### Claude Code Configuration

Add the MCP server to Claude Code using stdio transport:

```bash
# Local ROS master
claude mcp add ros \
  -e ROS_MASTER_URI=http://localhost:11311 \
  -- docker run -i --rm --network host \
  -e ROS_MASTER_URI \
  ros_mcp-ros-mcp-server --transport stdio
```

```bash
# Remote ROS master
claude mcp add ros \
  -e ROS_MASTER_URI=http://192.168.1.100:11311 \
  -e ROS_IP=192.168.1.50 \
  -- docker run -i --rm --network host \
  -e ROS_MASTER_URI -e ROS_IP \
  ros_mcp-ros-mcp-server --transport stdio
```

Other useful commands:

```bash
# List configured MCP servers
claude mcp list

# Remove the server
claude mcp remove ros
```

## Available Tools

### Topic Tools

| Tool | Description |
|------|-------------|
| `ros_list_topics` | List all active ROS topics |
| `ros_get_topic_info` | Get detailed information about a topic |
| `ros_publish` | Publish a message to a topic |
| `ros_subscribe_once` | Get a single message from a topic |
| `ros_echo_topic` | Get multiple messages from a topic |

### Service Tools

| Tool | Description |
|------|-------------|
| `ros_list_services` | List all available services |
| `ros_get_service_info` | Get service details |
| `ros_call_service` | Call a ROS service |

### Parameter Tools

| Tool | Description |
|------|-------------|
| `ros_list_params` | List all parameters |
| `ros_get_param` | Get a parameter value |
| `ros_set_param` | Set a parameter value |
| `ros_delete_param` | Delete a parameter |
| `ros_has_param` | Check if parameter exists |
| `ros_search_param` | Search for a parameter |

### Node Tools

| Tool | Description |
|------|-------------|
| `ros_list_nodes` | List all active nodes |
| `ros_get_node_info` | Get node publications, subscriptions, services |
| `ros_ping_node` | Check if a node is responsive |
| `ros_get_master_info` | Get ROS master information |

### Message Tools

| Tool | Description |
|------|-------------|
| `ros_show_msg` | Show message type definition |
| `ros_show_srv` | Show service type definition |
| `ros_list_msg_types` | List available message types |
| `ros_list_srv_types` | List available service types |
| `ros_msg_md5` | Get message type MD5 sum |

### TF Transform Tools

| Tool | Description |
|------|-------------|
| `ros_list_frames` | List all TF frames |
| `ros_lookup_transform` | Get transform between frames |
| `ros_can_transform` | Check if transform is available |
| `ros_get_frame_tree` | Get TF tree structure |
| `ros_transform_point` | Transform a point between frames |
| `ros_transform_pose` | Transform a pose between frames |

## Available Resources

| Resource URI | Description |
|--------------|-------------|
| `ros://system/status` | System connectivity status |
| `ros://topics` | List of all topics |
| `ros://nodes` | List of all nodes |
| `ros://services` | List of all services |
| `ros://params` | List of all parameters |
| `ros://topic/{name}` | Topic info and latest message |
| `ros://node/{name}` | Node information |
| `ros://param/{name}` | Parameter value |
| `ros://tf/frames` | List of TF frames |

## Example Usage

### List all topics
```
Use the ros_list_topics tool to see what topics are available.
```

### Get robot position
```
Use ros_subscribe_once on the /odom topic to get the current odometry.
```

### Send a velocity command
```
Use ros_publish to send a geometry_msgs/Twist message to /cmd_vel with linear.x = 0.5.
```

### Check TF transform
```
Use ros_lookup_transform to get the transform from base_link to map.
```

## Development

### Building locally

```bash
# Build the Docker image
docker build -t ros-mcp-server .

# Run with custom settings
docker run --network host \
  -e ROS_MASTER_URI=http://localhost:11311 \
  ros-mcp-server
```

### Running without Docker

Requires ROS Noetic environment:

```bash
# Source ROS
source /opt/ros/noetic/setup.bash

# Install dependencies
pip install -e .

# Run the server
python -m ros_mcp_server --transport http --port 8000
```

### Project Structure

```
ros_mcp/
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
├── requirements.txt
├── README.md
└── src/
    └── ros_mcp_server/
        ├── __init__.py
        ├── __main__.py
        ├── server.py
        ├── tools/
        │   ├── topics.py
        │   ├── services.py
        │   ├── params.py
        │   ├── nodes.py
        │   ├── messages.py
        │   └── transforms.py
        ├── resources/
        │   └── ros_resources.py
        └── utils/
            ├── ros_bridge.py
            └── message_utils.py
```

## Troubleshooting

### Cannot connect to ROS master

1. Ensure roscore is running
2. Check `ROS_MASTER_URI` is correct
3. Verify network connectivity (use `network_mode: host` in Docker)

### Transform lookup fails

1. Wait for TF data to be published
2. Check that both frames exist with `ros_list_frames`
3. Verify the transform chain exists with `ros_get_frame_tree`

### Message type not found

1. Ensure the message package is installed in the Docker container
2. For custom messages, mount the workspace or rebuild the Docker image

## License

MIT License

## References

- [FastMCP Documentation](https://gofastmcp.com)
- [ROS Noetic Documentation](http://wiki.ros.org/noetic)
- [MCP Protocol](https://modelcontextprotocol.io)