[English](README.md) | [日本語](README_ja.md) | **README**
# Rosbridge MCP Server
A Model Context Protocol (MCP) server that provides comprehensive tools for interacting with ROS (Robot Operating System) via rosbridge WebSocket connection. This Python implementation enables AI assistants to monitor and control ROS systems through a standardized interface.
## Features
- **Topic Operations**: List topics, get topic info, and publish messages
- **Service Operations**: List services and call ROS services
- **Action Operations**: List action servers, send goals, and cancel actions
## Usage
Choose one of these examples based on your needs:
**Basic usage (localhost):**
```json
{
"mcpServers": {
"rosbridge": {
"command": "uvx",
"args": ["takanarishimbo-rosbridge-mcp-server"]
}
}
}
```
**Custom rosbridge host:**
```json
{
"mcpServers": {
"rosbridge": {
"command": "uvx",
"args": ["takanarishimbo-rosbridge-mcp-server"],
"env": {
"ROSBRIDGE_HOST": "192.168.1.100",
"ROSBRIDGE_PORT": "9090"
}
}
}
}
```
**Remote ROS system:**
```json
{
"mcpServers": {
"rosbridge": {
"command": "uvx",
"args": ["rosbridge-mcp-server"],
"env": {
"ROSBRIDGE_HOST": "ros-robot.local",
"ROSBRIDGE_PORT": "9091"
}
}
}
}
```
## Configuration
The server can be configured using environment variables:
### `ROSBRIDGE_HOST`
The rosbridge server host (default: "localhost")
Examples:
- `localhost`: Local rosbridge
- `192.168.1.100`: Remote IP address
- `ros-robot.local`: Hostname
### `ROSBRIDGE_PORT`
The rosbridge server port (default: "9090")
Standard rosbridge WebSocket port is 9090.
## Available Tools
### Topic Operations
#### `list_topics`
List all available ROS topics with their types.
No parameters required.
#### `get_topic_info`
Get detailed information about a specific topic including publishers and subscribers.
Parameters:
- `topic` (required): The ROS topic name (e.g., "/cmd_vel")
#### `publish_topic`
Publish a message to a ROS topic.
Parameters:
- `topic` (required): The ROS topic name (e.g., "/cmd_vel")
- `message_type` (required): The ROS message type (e.g., "geometry_msgs/Twist")
- `message` (required): The message data as a JSON object
Example:
```json
{
"name": "publish_topic",
"arguments": {
"topic": "/cmd_vel",
"message_type": "geometry_msgs/Twist",
"message": {
"linear": { "x": 0.5, "y": 0.0, "z": 0.0 },
"angular": { "x": 0.0, "y": 0.0, "z": 0.1 }
}
}
}
```
### Service Operations
#### `list_services`
List all available ROS services.
No parameters required.
#### `publish_service`
Call a ROS service.
Parameters:
- `service` (required): The ROS service name (e.g., "/add_two_ints")
- `service_type` (required): The ROS service type (e.g., "rospy_tutorials/AddTwoInts")
- `request` (required): The service request data as a JSON object
- `timeout` (optional): Timeout in seconds (default: 10)
Example:
```json
{
"name": "publish_service",
"arguments": {
"service": "/add_two_ints",
"service_type": "rospy_tutorials/AddTwoInts",
"request": {
"a": 10,
"b": 20
}
}
}
```
### Action Operations
#### `list_actions`
List all available ROS action servers.
No parameters required.
#### `publish_action`
Send a goal to a ROS action server.
Parameters:
- `action_name` (required): The ROS action server name (e.g., "/move_base")
- `action_type` (required): The ROS action type (e.g., "move_base_msgs/MoveBaseAction")
- `goal` (required): The goal data as a JSON object
- `timeout` (optional): Timeout in seconds to wait for result (default: 30)
Example:
```json
{
"name": "publish_action",
"arguments": {
"action_name": "/move_base",
"action_type": "move_base_msgs/MoveBaseAction",
"goal": {
"target_pose": {
"header": {
"frame_id": "map"
},
"pose": {
"position": { "x": 1.0, "y": 2.0, "z": 0.0 },
"orientation": { "x": 0.0, "y": 0.0, "z": 0.0, "w": 1.0 }
}
}
}
}
}
```
#### `cancel_action`
Cancel a running ROS action goal.
Parameters:
- `action_name` (required): The ROS action server name (e.g., "/move_base")
- `goal_id` (optional): The specific goal ID to cancel (cancels all if not provided)
## Development
1. **Clone this repository**
```bash
git clone https://github.com/TakanariShimbo/rosbridge-mcp-server.git
cd rosbridge-mcp-server
```
2. **Install dependencies using uv**
```bash
uv sync
```
3. **Start rosbridge on your ROS system**
```bash
roslaunch rosbridge_server rosbridge_websocket.launch
```
4. **Run the server**
```bash
uv run takanarishimbo-rosbridge-mcp-server
```
5. **Test with MCP Inspector (optional)**
```bash
npx @modelcontextprotocol/inspector uv run takanarishimbo-rosbridge-mcp-server
```
## Publishing to PyPI
This project uses PyPI's Trusted Publishers feature for secure, token-less publishing via GitHub Actions.
### 1. Configure PyPI Trusted Publisher
1. **Log in to PyPI** (create account if needed)
- Go to https://pypi.org/
2. **Navigate to Publishing Settings**
- Go to your account settings
- Click on "Publishing" or go to https://pypi.org/manage/account/publishing/
3. **Add GitHub Publisher**
- Click "Add a new publisher"
- Select "GitHub" as the publisher
- Fill in:
- **Owner**: `TakanariShimbo` (your GitHub username/org)
- **Repository**: `rosbridge-mcp-server`
- **Workflow name**: `pypi-publish.yml`
- **Environment**: `pypi` (optional but recommended)
- Click "Add"
### 2. Configure GitHub Environment (Recommended)
1. **Navigate to Repository Settings**
- Go to your GitHub repository
- Click "Settings" → "Environments"
2. **Create PyPI Environment**
- Click "New environment"
- Name: `pypi`
- Configure protection rules (optional):
- Add required reviewers
- Restrict to specific branches/tags
### 3. Setup GitHub Personal Access Token (for release script)
The release script needs to push to GitHub, so you'll need a GitHub token:
1. **Create GitHub Personal Access Token**
- Go to https://github.com/settings/tokens
- Click "Generate new token" → "Generate new token (classic)"
- Set expiration (recommended: 90 days or custom)
- Select scopes:
- ✅ `repo` (Full control of private repositories)
- Click "Generate token"
- Copy the generated token (starts with `ghp_`)
2. **Configure Git with Token**
```bash
# Option 1: Use GitHub CLI (recommended)
gh auth login
# Option 2: Configure git to use token
git config --global credential.helper store
# Then when prompted for password, use your token instead
```
### 4. Release New Version
Use the release script to automatically version, tag, and trigger publishing:
```bash
# First time setup
chmod +x scripts/release.sh
# Increment patch version (0.1.0 → 0.1.1)
./scripts/release.sh patch
# Increment minor version (0.1.0 → 0.2.0)
./scripts/release.sh minor
# Increment major version (0.1.0 → 1.0.0)
./scripts/release.sh major
# Set specific version
./scripts/release.sh 1.2.3
```
### 5. Verify Publication
1. **Check GitHub Actions**
- Go to "Actions" tab in your repository
- Verify the "Publish to PyPI" workflow completed successfully
2. **Verify PyPI Package**
- Visit: https://pypi.org/project/rosbridge-mcp-server/
- Or run: `pip show rosbridge-mcp-server`
### Release Process Flow
1. `release.sh` script updates version in all files
2. Creates git commit and tag
3. Pushes to GitHub
4. GitHub Actions workflow triggers on new tag
5. Workflow uses OIDC to authenticate with PyPI (no tokens needed!)
6. Workflow builds project and publishes to PyPI
7. Package becomes available globally via `pip install` or `uvx`
## Code Quality
This project uses `ruff` for linting and formatting:
```bash
# Run linter
uv run ruff check
# Fix linting issues
uv run ruff check --fix
# Format code
uv run ruff format
```
## Project Structure
```
rosbridge-mcp-server/
├── src/
│ ├── __init__.py # Package initialization
│ ├── __main__.py # Main entry point
│ ├── server.py # Server implementation
│ └── tools/ # Tool implementations
│ ├── __init__.py # Tools module initialization
│ ├── list_topics.py # List topics tool
│ ├── list_actions.py # List actions tool
│ ├── list_services.py # List services tool
│ ├── get_topic_info.py # Get topic info tool
│ ├── publish_topic.py # Publish topic tool
│ ├── publish_action.py # Publish action tool
│ ├── publish_service.py # Publish service tool
│ └── cancel_action.py # Cancel action tool
├── pyproject.toml # Project configuration
├── uv.lock # Dependency lock file
├── .github/
│ └── workflows/
│ └── pypi-publish.yml # PyPI publish workflow with Trusted Publishers
├── scripts/
│ └── release.sh # Release automation script
├── docs/
│ ├── README.md # English documentation
│ └── README_ja.md # Japanese documentation
└── .gitignore # Git ignore file
```
## License
MIT
Raw data
{
"_id": null,
"home_page": null,
"name": "takanarishimbo-rosbridge-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "mcp, robotics, ros, rosbridge, server",
"author": null,
"author_email": "Takanari Shimbo <takanari.shimbo@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/8e/10/bd45d524fb112cacfe9d05d689d084c90f1d416905533b19920946f0e0ab/takanarishimbo_rosbridge_mcp_server-0.3.0.tar.gz",
"platform": null,
"description": "[English](README.md) | [\u65e5\u672c\u8a9e](README_ja.md) | **README**\n\n# Rosbridge MCP Server\n\nA Model Context Protocol (MCP) server that provides comprehensive tools for interacting with ROS (Robot Operating System) via rosbridge WebSocket connection. This Python implementation enables AI assistants to monitor and control ROS systems through a standardized interface.\n\n## Features\n\n- **Topic Operations**: List topics, get topic info, and publish messages\n- **Service Operations**: List services and call ROS services\n- **Action Operations**: List action servers, send goals, and cancel actions\n\n## Usage\n\nChoose one of these examples based on your needs:\n\n**Basic usage (localhost):**\n\n```json\n{\n \"mcpServers\": {\n \"rosbridge\": {\n \"command\": \"uvx\",\n \"args\": [\"takanarishimbo-rosbridge-mcp-server\"]\n }\n }\n}\n```\n\n**Custom rosbridge host:**\n\n```json\n{\n \"mcpServers\": {\n \"rosbridge\": {\n \"command\": \"uvx\",\n \"args\": [\"takanarishimbo-rosbridge-mcp-server\"],\n \"env\": {\n \"ROSBRIDGE_HOST\": \"192.168.1.100\",\n \"ROSBRIDGE_PORT\": \"9090\"\n }\n }\n }\n}\n```\n\n**Remote ROS system:**\n\n```json\n{\n \"mcpServers\": {\n \"rosbridge\": {\n \"command\": \"uvx\",\n \"args\": [\"rosbridge-mcp-server\"],\n \"env\": {\n \"ROSBRIDGE_HOST\": \"ros-robot.local\",\n \"ROSBRIDGE_PORT\": \"9091\"\n }\n }\n }\n}\n```\n\n## Configuration\n\nThe server can be configured using environment variables:\n\n### `ROSBRIDGE_HOST`\n\nThe rosbridge server host (default: \"localhost\")\n\nExamples:\n\n- `localhost`: Local rosbridge\n- `192.168.1.100`: Remote IP address\n- `ros-robot.local`: Hostname\n\n### `ROSBRIDGE_PORT`\n\nThe rosbridge server port (default: \"9090\")\n\nStandard rosbridge WebSocket port is 9090.\n\n## Available Tools\n\n### Topic Operations\n\n#### `list_topics`\n\nList all available ROS topics with their types.\n\nNo parameters required.\n\n#### `get_topic_info`\n\nGet detailed information about a specific topic including publishers and subscribers.\n\nParameters:\n\n- `topic` (required): The ROS topic name (e.g., \"/cmd_vel\")\n\n#### `publish_topic`\n\nPublish a message to a ROS topic.\n\nParameters:\n\n- `topic` (required): The ROS topic name (e.g., \"/cmd_vel\")\n- `message_type` (required): The ROS message type (e.g., \"geometry_msgs/Twist\")\n- `message` (required): The message data as a JSON object\n\nExample:\n\n```json\n{\n \"name\": \"publish_topic\",\n \"arguments\": {\n \"topic\": \"/cmd_vel\",\n \"message_type\": \"geometry_msgs/Twist\",\n \"message\": {\n \"linear\": { \"x\": 0.5, \"y\": 0.0, \"z\": 0.0 },\n \"angular\": { \"x\": 0.0, \"y\": 0.0, \"z\": 0.1 }\n }\n }\n}\n```\n\n### Service Operations\n\n#### `list_services`\n\nList all available ROS services.\n\nNo parameters required.\n\n#### `publish_service`\n\nCall a ROS service.\n\nParameters:\n\n- `service` (required): The ROS service name (e.g., \"/add_two_ints\")\n- `service_type` (required): The ROS service type (e.g., \"rospy_tutorials/AddTwoInts\")\n- `request` (required): The service request data as a JSON object\n- `timeout` (optional): Timeout in seconds (default: 10)\n\nExample:\n\n```json\n{\n \"name\": \"publish_service\",\n \"arguments\": {\n \"service\": \"/add_two_ints\",\n \"service_type\": \"rospy_tutorials/AddTwoInts\",\n \"request\": {\n \"a\": 10,\n \"b\": 20\n }\n }\n}\n```\n\n### Action Operations\n\n#### `list_actions`\n\nList all available ROS action servers.\n\nNo parameters required.\n\n#### `publish_action`\n\nSend a goal to a ROS action server.\n\nParameters:\n\n- `action_name` (required): The ROS action server name (e.g., \"/move_base\")\n- `action_type` (required): The ROS action type (e.g., \"move_base_msgs/MoveBaseAction\")\n- `goal` (required): The goal data as a JSON object\n- `timeout` (optional): Timeout in seconds to wait for result (default: 30)\n\nExample:\n\n```json\n{\n \"name\": \"publish_action\",\n \"arguments\": {\n \"action_name\": \"/move_base\",\n \"action_type\": \"move_base_msgs/MoveBaseAction\",\n \"goal\": {\n \"target_pose\": {\n \"header\": {\n \"frame_id\": \"map\"\n },\n \"pose\": {\n \"position\": { \"x\": 1.0, \"y\": 2.0, \"z\": 0.0 },\n \"orientation\": { \"x\": 0.0, \"y\": 0.0, \"z\": 0.0, \"w\": 1.0 }\n }\n }\n }\n }\n}\n```\n\n#### `cancel_action`\n\nCancel a running ROS action goal.\n\nParameters:\n\n- `action_name` (required): The ROS action server name (e.g., \"/move_base\")\n- `goal_id` (optional): The specific goal ID to cancel (cancels all if not provided)\n\n## Development\n\n1. **Clone this repository**\n\n ```bash\n git clone https://github.com/TakanariShimbo/rosbridge-mcp-server.git\n cd rosbridge-mcp-server\n ```\n\n2. **Install dependencies using uv**\n\n ```bash\n uv sync\n ```\n\n3. **Start rosbridge on your ROS system**\n\n ```bash\n roslaunch rosbridge_server rosbridge_websocket.launch\n ```\n\n4. **Run the server**\n\n ```bash\n uv run takanarishimbo-rosbridge-mcp-server\n ```\n\n5. **Test with MCP Inspector (optional)**\n\n ```bash\n npx @modelcontextprotocol/inspector uv run takanarishimbo-rosbridge-mcp-server\n ```\n\n## Publishing to PyPI\n\nThis project uses PyPI's Trusted Publishers feature for secure, token-less publishing via GitHub Actions.\n\n### 1. Configure PyPI Trusted Publisher\n\n1. **Log in to PyPI** (create account if needed)\n\n - Go to https://pypi.org/\n\n2. **Navigate to Publishing Settings**\n\n - Go to your account settings\n - Click on \"Publishing\" or go to https://pypi.org/manage/account/publishing/\n\n3. **Add GitHub Publisher**\n - Click \"Add a new publisher\"\n - Select \"GitHub\" as the publisher\n - Fill in:\n - **Owner**: `TakanariShimbo` (your GitHub username/org)\n - **Repository**: `rosbridge-mcp-server`\n - **Workflow name**: `pypi-publish.yml`\n - **Environment**: `pypi` (optional but recommended)\n - Click \"Add\"\n\n### 2. Configure GitHub Environment (Recommended)\n\n1. **Navigate to Repository Settings**\n\n - Go to your GitHub repository\n - Click \"Settings\" \u2192 \"Environments\"\n\n2. **Create PyPI Environment**\n - Click \"New environment\"\n - Name: `pypi`\n - Configure protection rules (optional):\n - Add required reviewers\n - Restrict to specific branches/tags\n\n### 3. Setup GitHub Personal Access Token (for release script)\n\nThe release script needs to push to GitHub, so you'll need a GitHub token:\n\n1. **Create GitHub Personal Access Token**\n\n - Go to https://github.com/settings/tokens\n - Click \"Generate new token\" \u2192 \"Generate new token (classic)\"\n - Set expiration (recommended: 90 days or custom)\n - Select scopes:\n - \u2705 `repo` (Full control of private repositories)\n - Click \"Generate token\"\n - Copy the generated token (starts with `ghp_`)\n\n2. **Configure Git with Token**\n\n ```bash\n # Option 1: Use GitHub CLI (recommended)\n gh auth login\n\n # Option 2: Configure git to use token\n git config --global credential.helper store\n # Then when prompted for password, use your token instead\n ```\n\n### 4. Release New Version\n\nUse the release script to automatically version, tag, and trigger publishing:\n\n```bash\n# First time setup\nchmod +x scripts/release.sh\n\n# Increment patch version (0.1.0 \u2192 0.1.1)\n./scripts/release.sh patch\n\n# Increment minor version (0.1.0 \u2192 0.2.0)\n./scripts/release.sh minor\n\n# Increment major version (0.1.0 \u2192 1.0.0)\n./scripts/release.sh major\n\n# Set specific version\n./scripts/release.sh 1.2.3\n```\n\n### 5. Verify Publication\n\n1. **Check GitHub Actions**\n\n - Go to \"Actions\" tab in your repository\n - Verify the \"Publish to PyPI\" workflow completed successfully\n\n2. **Verify PyPI Package**\n - Visit: https://pypi.org/project/rosbridge-mcp-server/\n - Or run: `pip show rosbridge-mcp-server`\n\n### Release Process Flow\n\n1. `release.sh` script updates version in all files\n2. Creates git commit and tag\n3. Pushes to GitHub\n4. GitHub Actions workflow triggers on new tag\n5. Workflow uses OIDC to authenticate with PyPI (no tokens needed!)\n6. Workflow builds project and publishes to PyPI\n7. Package becomes available globally via `pip install` or `uvx`\n\n## Code Quality\n\nThis project uses `ruff` for linting and formatting:\n\n```bash\n# Run linter\nuv run ruff check\n\n# Fix linting issues\nuv run ruff check --fix\n\n# Format code\nuv run ruff format\n```\n\n## Project Structure\n\n```\nrosbridge-mcp-server/\n\u251c\u2500\u2500 src/\n\u2502 \u251c\u2500\u2500 __init__.py # Package initialization\n\u2502 \u251c\u2500\u2500 __main__.py # Main entry point\n\u2502 \u251c\u2500\u2500 server.py # Server implementation\n\u2502 \u2514\u2500\u2500 tools/ # Tool implementations\n\u2502 \u251c\u2500\u2500 __init__.py # Tools module initialization\n\u2502 \u251c\u2500\u2500 list_topics.py # List topics tool\n\u2502 \u251c\u2500\u2500 list_actions.py # List actions tool\n\u2502 \u251c\u2500\u2500 list_services.py # List services tool\n\u2502 \u251c\u2500\u2500 get_topic_info.py # Get topic info tool\n\u2502 \u251c\u2500\u2500 publish_topic.py # Publish topic tool\n\u2502 \u251c\u2500\u2500 publish_action.py # Publish action tool\n\u2502 \u251c\u2500\u2500 publish_service.py # Publish service tool\n\u2502 \u2514\u2500\u2500 cancel_action.py # Cancel action tool\n\u251c\u2500\u2500 pyproject.toml # Project configuration\n\u251c\u2500\u2500 uv.lock # Dependency lock file\n\u251c\u2500\u2500 .github/\n\u2502 \u2514\u2500\u2500 workflows/\n\u2502 \u2514\u2500\u2500 pypi-publish.yml # PyPI publish workflow with Trusted Publishers\n\u251c\u2500\u2500 scripts/\n\u2502 \u2514\u2500\u2500 release.sh # Release automation script\n\u251c\u2500\u2500 docs/\n\u2502 \u251c\u2500\u2500 README.md # English documentation\n\u2502 \u2514\u2500\u2500 README_ja.md # Japanese documentation\n\u2514\u2500\u2500 .gitignore # Git ignore file\n```\n\n## License\n\nMIT\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A MCP server that provides ROS topic publishing functionality via rosbridge",
"version": "0.3.0",
"project_urls": {
"Homepage": "https://github.com/TakanariShimbo/rosbridge-mcp-server",
"Issues": "https://github.com/TakanariShimbo/rosbridge-mcp-server/issues",
"Repository": "https://github.com/TakanariShimbo/rosbridge-mcp-server.git"
},
"split_keywords": [
"mcp",
" robotics",
" ros",
" rosbridge",
" server"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c2b30387d40579b6064f165b873cb2bec520ad1c4a987c9daa3f72a7355b86ba",
"md5": "6bb4857a63eff889ab8c6b1394840696",
"sha256": "a86f07f1513b623e541f53a82b72a223f4d05ef02d6af75979a7a8009e36f733"
},
"downloads": -1,
"filename": "takanarishimbo_rosbridge_mcp_server-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6bb4857a63eff889ab8c6b1394840696",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 17317,
"upload_time": "2025-07-31T07:46:24",
"upload_time_iso_8601": "2025-07-31T07:46:24.343209Z",
"url": "https://files.pythonhosted.org/packages/c2/b3/0387d40579b6064f165b873cb2bec520ad1c4a987c9daa3f72a7355b86ba/takanarishimbo_rosbridge_mcp_server-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8e10bd45d524fb112cacfe9d05d689d084c90f1d416905533b19920946f0e0ab",
"md5": "319bc5832177c6fcefa6f09ddce51a1c",
"sha256": "f0458803ddf4caa281d98a73535065274c6c7520db739d91be4ec3b1f40bcccb"
},
"downloads": -1,
"filename": "takanarishimbo_rosbridge_mcp_server-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "319bc5832177c6fcefa6f09ddce51a1c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 12466,
"upload_time": "2025-07-31T07:46:25",
"upload_time_iso_8601": "2025-07-31T07:46:25.524887Z",
"url": "https://files.pythonhosted.org/packages/8e/10/bd45d524fb112cacfe9d05d689d084c90f1d416905533b19920946f0e0ab/takanarishimbo_rosbridge_mcp_server-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-31 07:46:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "TakanariShimbo",
"github_project": "rosbridge-mcp-server",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "takanarishimbo-rosbridge-mcp-server"
}
JSON
