What is rosbridge-mcp CLAUDE.md?

A set of Claude Code instructions for connecting an AI agent to ROS 2 robots through rosbridge. ROS 2 is a robotics software platform, while rosbridge provides a WebSocket and JSON connection to a robot without requiring ROS to be installed on the client machine.

Running, testing, and configuring an MCP server that communicates with ROS 2 robots, including local mock-server testing without a real robot.

It documents the project layout, setup, environment variables, read-only behavior, and testing approach needed to use the connection safely.

How hieutachi/rosbridge-mcp configures Claude Code

Reuse

Borrowing it

Nothing to install: this file belongs to hieutachi/rosbridge-mcp. Take a copy, put it at the same path in your own repository, and replace the rules that are about this project with yours.

Copy the file

curl -O https://raw.githubusercontent.com/hieutachi/rosbridge-mcp/main/CLAUDE.md

Clone the repo

git clone --depth 1 https://github.com/hieutachi/rosbridge-mcp

Made for: Claude Code.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

README.md

[![agentmods](https://agentmods.dev/badge/instructions/hieutachi/rosbridge-mcp/claude-md/github.svg)](https://agentmods.dev/instructions/hieutachi/rosbridge-mcp/claude-md)

Your own site

<a href="https://agentmods.dev/instructions/hieutachi/rosbridge-mcp/claude-md"><img src="https://agentmods.dev/badge/instructions/hieutachi/rosbridge-mcp/claude-md/github.svg" alt="Measured on agentmods" height="20"></a>

Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.

Your own site · 80×15

<a href="https://agentmods.dev/instructions/hieutachi/rosbridge-mcp/claude-md"><img src="https://agentmods.dev/badge/instructions/hieutachi/rosbridge-mcp/claude-md.svg" alt="Reviewed on agentmods" width="80" height="20"></a>

Per session 588 This file is loaded in full into every session.

When invoked 588 The same file — it is already loaded in full.

Security scan A 0 findings. A grade says what 26 rules found in the file — not that it is safe.

Origin original No closer match found in the catalogue.

Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

Model	Per session	Once invoked
Fable 5.1	$0.00588	$0.00588
Opus 5	$0.00294	$0.00294
Sonnet 5	$0.00118	$0.00118
Haiku 4.5	$0.00059	$0.00059

Measured 10d ago against content hash 80e9468db9a5, method: parsed. Prices are Anthropic first-party input rates as of 2026-09-10, from the pricing page.

Security

Grade A, and why

rosbridge-mcp CLAUDE.md scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 10d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

CLAUDE.md · 57 lines

How it starts

The opening of the file, as written. The whole thing — 57 lines — stays where its author put it; the contents beside it link to each section on GitHub.

CLAUDE.md

Project context for Claude Code. rosbridge-mcp is an MCP server that connects AI agents to ROS 2 robots over rosbridge (WebSocket + JSON). The client machine does not need a ROS install.

Layout

rosbridge_mcp/client.py — rosbridge v2 protocol client (WebSocket, reconnect, correlation)
rosbridge_mcp/server.py — FastMCP app and 11 tools; readonly policy lives here
rosbridge_mcp/mock_server.py — in-process fake rosbridge for tests and local demos
tests/ — pytest, no ROS/network required
docs/ — per-client and safety guides
examples/ — Claude Desktop / Cursor MCP configs and demo.py

Run

python -m venv .venv
.venv\Scripts\activate          # macOS/Linux: source .venv/bin/activate
pip install -e ".[dev]"
pytest
rosbridge-mcp                   # stdio MCP server

Against a mock (no robot):

python -m rosbridge_mcp.mock_server 9090
# then ROSBRIDGE_URL=ws://localhost:9090

Install from Git: pip install git+https://github.com/hieutachi/rosbridge-mcp.git

Environment

Variable	Default	Meaning
`ROSBRIDGE_URL`	`ws://localhost:9090`	rosbridge WebSocket
`ROSBRIDGE_MCP_READONLY`	unset/false	When `1`/`true`/`yes`, mutating tools are rejected

Start real-robot sessions with readonly on. See docs/real-robot-safety.md.

Tools

Read-only: list_topics, list_nodes, list_services, get_topic_snapshot, get_tf_tree, get_camera_image, get_connection_status.

Mutating (blocked in readonly): publish_message, send_action_goal, cancel_action_goal. call_service is mutating except a frozen allowlist of /rosapi introspection services in READONLY_SAFE_ROSAPI.

All tools return JSON. Message payloads use rosbridge's JSON mapping of ROS .msg/.srv/.action fields.

Conventions

Conventional Commits (feat:, fix:, docs:) and DCO (git commit -s)
Do not add runtime dependencies without discussion; keep licenses permissive
Do not expose rosbridge to the public internet; it has no auth by default
Do not publish to PyPI unless explicitly asked
Do not change .github/workflows unless the request includes workflow-scope access

Read the full file on GitHub · 57 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

10d ago First seen · 57 lines · 588 tokens per session scan A 80e9468db9a5

Subscribe to this mod's changes

rosbridge-mcp CLAUDE.md is an instructions file published in the GitHub repository hieutachi/rosbridge-mcp (2 stars, last pushed 23d ago), licensed MIT. It adds 588 tokens to every session, about $0.0029 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.

Hardware and IoT ai-agent mcp model-context-protocol robotics ros2 rosbridge

next.js AGENTS.md

AGENTS.md instructions for vercel/next.js, covering next.js development guide, codebase structure, monorepo overview, core package: packages/next and other important packages.

vercel/next.js · 7,296 tokens

codex AGENTS.md

AGENTS.md instructions for openai/codex, covering rust/codex-rs, the codex-core crate, code review rules, crate api surface and model visible context.

openai/codex · 5,153 tokens

vscode buildNext.instructions.md

Working notes and architecture documentation for the new esbuild-based build system in build/next. Use when making changes to the new build pipeline (transpile/bundle commands, NLS plugin, source-map handling, resource copying, or self-hosting watch tasks).

microsoft/vscode · 6,785 tokens

rosbridge-mcp: Instructions file for Claude Code