RViz Map Image MCP

FastMCP tools for converting a live ROS 2 occupancy map into a shareable image. The server subscribes to the same nav_msgs/msg/OccupancyGrid data that RViz uses for a 2D map display, usually /map, then returns PNG/JPEG images, base64 payloads, metadata, corner goals, and optional Nav2 navigation commands.

This is useful when an AI agent needs to inspect the robot's current map, send the map image to a user, convert between map coordinates and pixels, or navigate to coarse locations such as the map corners.

Features

• Render a live ROS 2 occupancy grid as an RViz-style map image.
• Return images as base64, data URIs, or saved PNG/JPEG files.
• Include map metadata: resolution, origin, image size, occupancy statistics, and pixel-to-world conventions.
• Mark the robot pose and safe corner goals on the rendered image.
• Convert map-frame world coordinates to rendered-image pixels and back.
• Find safe free-space goals near top_left, top_right, bottom_left, and bottom_right.
• Validate candidate navigation goals against the map and optional costmap.
• Send Nav2 NavigateToPose goals to coordinates or named corners.

Files

occupancy_map_to_image.py   One-shot CLI map capture script
map_image_mcp_server.py     FastMCP server with map image and navigation tools
mcp_config_example.json     Example MCP client configuration
requirements.txt            Python dependencies outside the ROS install

Requirements

• ROS 2 with Python support, tested with Humble-era APIs.
• A live nav_msgs/msg/OccupancyGrid topic such as /map.
• For navigation tools: Nav2 nav2_msgs/action/NavigateToPose.
• Python packages:

python3 -m pip install --user -r requirements.txt

ROS message packages such as rclpy, nav_msgs, geometry_msgs, nav2_msgs, and tf2_ros should come from your ROS 2 installation, not pip.

One-Shot Map Capture

cd /home/bharat/Desktop/rviz_map_image_mcp
python3 occupancy_map_to_image.py \
  --map-topic /map \
  --output /home/bharat/Desktop/rviz_map_captures/latest_map.png \
  --draw-corners \
  --draw-legend

Useful options:

--return-base64       include base64 image data in the JSON output
--scale 2             render at 2 pixels per map cell before max-side limiting
--max-image-side 1600 cap the longest rendered side
--no-flip-y           keep raw occupancy-grid row order
--use-sim-time        use ROS simulated time

The command prints JSON with the saved image path, map metadata, and optionally base64 image data.

MCP Server

Run over stdio:

cd /home/bharat/Desktop/rviz_map_image_mcp
python3 map_image_mcp_server.py --transport stdio

Run over streamable HTTP:

cd /home/bharat/Desktop/rviz_map_image_mcp
python3 map_image_mcp_server.py \
  --transport streamable-http \
  --host 127.0.0.1 \
  --port 8767

Default ROS topics and frames:

/map
/global_costmap/costmap
/odom
/navigate_to_pose
map
base_footprint

Override them with CLI flags or the configure_topics MCP tool.

MCP Client Config

Stdio example:

{
  "mcpServers": {
    "rviz-map-image-stdio": {
      "name": "RViz Map Image MCP",
      "transport": "stdio",
      "command": "python3",
      "args": [
        "/home/bharat/Desktop/rviz_map_image_mcp/map_image_mcp_server.py",
        "--transport",
        "stdio"
      ]
    }
  }
}

HTTP example:

{
  "mcpServers": {
    "rviz-map-image-http": {
      "name": "RViz Map Image MCP HTTP",
      "transport": "http",
      "url": "http://127.0.0.1:8767/mcp"
    }
  }
}

MCP Tools

server_status
list_map_topics
configure_topics
summarize_map
get_map_image
save_map_image
get_map_corners
world_to_pixel
pixel_to_world
get_robot_pose
validate_goal
navigate_to_coordinate
navigate_to_corner

Image Tools

get_map_image returns an image and metadata. Important options:

return_base64=true       return image_base64 and mime_type
save=true                save a copy to disk
save_path=...            choose a specific output path
draw_robot=true          overlay the current robot pose when TF/odom is available
draw_corners=true        overlay safe corner goals
draw_legend=true         overlay occupancy legend
scale=1.0
max_image_side=1600

save_map_image is a convenience wrapper that saves by default under:

/home/bharat/Desktop/rviz_map_captures

Coordinate Tools

With the default flip_y=true, image right is +map_x and image up is +map_y, matching the normal top-down RViz view. The server returns the exact image dimensions and transform metadata with each rendered image.

Use:

world_to_pixel
pixel_to_world

to connect visual annotations back to map-frame coordinates.

Navigation Tools

get_map_corners returns safe free-space goals near:

top_left
top_right
bottom_left
bottom_right

navigate_to_corner accepts those IDs, plus:

nearest
farthest

navigate_to_coordinate sends a Nav2 NavigateToPose action after optional goal validation.

Notes

This server reads the ROS occupancy grid, not RViz internals. RViz and this tool should show the same map when they subscribe to the same /map topic.

The companion UGV workspace package src/ugv_main/ugv_navigation_mcp provides more geometry-focused navigation tools, including Hough-style room-corner detection. This project is focused on visual map access and lightweight map-corner interaction for AI agents.