Skip to content
WiseVision Docs

Quickstart: ROS2 MCP with Docker in 5 minutes

You need Docker and an MCP client (Claude Code, Claude Desktop, Cursor, Codex, VS Code, …). You do not need ROS 2 installed: the server image contains it.

1. Start a demo robot

Section titled “1. Start a demo robot”

If you already have a ROS 2 system running, skip to step 2. Otherwise, start a container that publishes std_msgs/msg/String on /chatter twice a second:

Terminal window
docker run -d --name demo-robot ros:jazzy-ros-base \
  bash -c 'source /opt/ros/jazzy/setup.bash && ros2 topic pub -r 2 /chatter std_msgs/msg/String "{data: hello from the robot}"'

2. Add ROS2 MCP to your agent

Section titled “2. Add ROS2 MCP to your agent”

The server speaks MCP over stdio, so your client starts it as a subprocess. The command is:

Terminal window
docker run -i --rm wisevision/ros2_mcp:jazzy

Use wisevision/ros2_mcp:humble for a ROS 2 Humble system. With Claude Code, one line registers it:

Terminal window
claude mcp add ros2 -- docker run -i --rm wisevision/ros2_mcp:jazzy

For other clients, see Connect your agent. Restart the client (or reload its MCP servers) after changing the config.

3. Ask your agent

Section titled “3. Ask your agent”

Try:

  • “List the ROS 2 topics.”
  • “Read three messages from /chatter.”

The agent calls ros2_topic_list, then ros2_topic_subscribe, and gets back:

[/chatter] 3 messages received.
{ "/chatter#0": { "_data": "hello from the robot", ... } }

If the agent sees no topics or no messages

Section titled “If the agent sees no topics or no messages”
  • ROS_DOMAIN_ID. If your robot uses a domain ID other than 0, pass the same one: docker run -i --rm -e ROS_DOMAIN_ID=<id> wisevision/ros2_mcp:jazzy.
  • ROS 2 runs on the host itself (not in a container). Add --network host --ipc host. Without --ipc host the topics are listed, but messages sent over Fast DDS shared memory do not arrive.
  • The robot is another machine on your network. DDS discovery uses multicast, which Docker’s default bridge network does not forward. Add --network host.
  • Right after start-up the list is incomplete. DDS discovery can take a moment. The server waits for it once, on the first call; tune it with MCP_ROS_DISCOVERY_STABLE_SEC (default 1.0) and MCP_ROS_DISCOVERY_TIMEOUT_SEC (default 5.0).
  • Custom message types. Build your message packages into ~/mcp_custom_messages and mount it: -v ~/mcp_custom_messages:/app/custom_msgs. See the FAQ.

Clean up

Section titled “Clean up”
Terminal window
docker rm -f demo-robot

Next

Section titled “Next”