ros2-image-mcp

MCP server (FastMCP) that exposes ROS 2 sensor_msgs/Image topics to VLMs and agents.

Tools: get_latest_ros_image · get_recent_ros_image_frames

Requirements

• ROS 2 sourced (source /opt/ros/<distro>/setup.bash)
• Python 3.10+

Install

source /opt/ros/humble/setup.bash   # or your distro
cd /path/to/ros2_img_mcp
pip install -U pip setuptools
pip install -e .

Optional demo extras: pip install -e ".[langgraph-demo]"

Quick start

1. Publish images on a topic (synthetic test pattern, or a real camera):

   python3 scripts/publish_test_image.py --topic /test/camera/image
   # webcam example: add --device 4   (for /dev/video4)
   

2. Run the MCP server (separate terminal, ROS sourced):

   ros2-image-mcp --default-topic /test/camera/image
   

3. Point your MCP client at the server — stdio (default above) or HTTP:

   ros2-image-mcp --default-topic /test/camera/image --transport http --port 8012
   

   HTTP endpoint: http://127.0.0.1:8012/mcp (path /mcp by default).

Cursor (stdio) — ROS must be sourced inside the command:

{
  "mcpServers": {
    "ros2-camera": {
      "command": "bash",
      "args": [
        "-lc",
        "source /opt/ros/humble/setup.bash && ros2-image-mcp --default-topic /test/camera/image"
      ]
    }
  }
}

LangGraph-style HTTP — transport: "http" and url: "http://127.0.0.1:8012/mcp" (or streamable_http if your client expects that name; URL unchanged).

Limitations

• Depth / float formats (e.g. 32FC1) are not converted; use an RGB topic or encode to png/jpeg on the ROS side.
• Very large images are heavy on MCP payloads; consider downscaling in ROS if needed.

More detail : DEVELOPERS.md