Skip to main content
Glama

ai-rover-mcp

MCP server for AI Rover Studio, a 2D robot simulator that runs in the browser. It lets an AI agent (Claude Code, Claude Desktop or any MCP client) observe and drive the rover, change its body, run programs and read the real wiring for an ESP32 / Arduino Uno / Raspberry Pi. Simulation only: nothing is sent to hardware.

MCP client ──stdio──▶ ai-rover-mcp ──WebSocket 127.0.0.1:8765──▶ simulator page in your browser

The page must be open in a browser and the tab must stay visible, because browsers pause animation frames in background tabs, so the simulation stops there. The badge in the page header shows MCP ● connected while the bridge is up.

Setup

Needs Node.js 18 or newer.

Claude Code

claude mcp add ai-rover -- npx -y ai-rover-mcp

Then ask Claude to "open the rover simulator". open_simulator opens the hosted simulator with ?mcp=on, which tells the page to connect to this server.

Claude Desktop / other clients

{
  "mcpServers": {
    "ai-rover": {
      "command": "npx",
      "args": ["-y", "ai-rover-mcp"]
    }
  }
}

From a clone

npm install
claude mcp add ai-rover -- node /path/to/ai-rover-mcp/server.js

Related MCP server: tinkercad-mcp-server

Opening the simulator yourself

Open https://ai-rover.app/app/?mcp=on. Without ?mcp=on the hosted page does not try to reach a local MCP server; you can also press เชื่อมต่อ MCP on its Agent / MCP page. A copy opened from disk (file://) or from localhost connects on its own.

Tools

Tool

What it does

open_simulator

Opens the simulator (hosted, or ROVER_SIMULATOR_URL) in the default browser and waits for it to connect

connection_status

Whether the page is connected

get_observation

Pose, velocity, sensor readings, face state and simulation status

read_sensors

Fresh readings from the enabled sensors, with mounting info and units

drive

forward / backward / left / right for 0.2–10 s; waits by default and returns the new observation

turn

Turn on the spot by an exact angle

stop

Emergency stop: cancels movement, turns autopilot off, pauses

set_simulation

Start or pause the simulation

set_autopilot

Rule-based autopilot (seek light, avoid obstacles) on or off

set_power

Motor power, 10–100 %

set_head / get_head

Head pan servo: turn to an angle, or track the light

press_button / get_button_events

Press a push button on the rover / read presses made by a person

run_program / stop_program / get_program

Run JavaScript that uses the rover library in the page, stop it, read its status and console

set_emotion

Face expression on the display, with a message in the top line

display_text

The rover "says" a text: small face + speech bubble on the Face Display (Thai supported)

set_display

Fit a display module: ssd1306 (128×64 mono OLED), ssd1331 (96×64 colour OLED) or st7789 (240×240 colour TFT)

draw_display

Show a picture on the Face Display from rows of characters

read_display

What the display shows: mode, stats and pixels as ASCII art

move_light

Move the light source

reset_world

Rover and light back to their start positions

send_chat

Send text to the in-page Agent Chat parser and get its reply

get_manifest

Robot Capability Manifest (ai-cartridge/body-v1)

list_sensors / add_sensor / update_sensor / remove_sensor

Configure the sensors on the robot body

set_module

Fit or remove wheels, head, display or camera

capture_camera

Picture from the rover's forward camera (PNG image) plus detections with bearing and distance

get_sensor_map

Map the rover built from its own sensors: occupancy grid, floor colors, camera landmarks, bump points

get_wiring

Circuit for the fitted body on esp32, uno or raspberrypi: every pin, power budget, wiring issues, pins.h / pins.py

get_firmware

Complete firmware for the fitted body: Arduino .ino or Raspberry Pi rover.py

get_bom

Parts list to build the fitted body for real, with quantities, approximate prices and shop links

list_world

World layout: light, obstacles, colored floor tape

add_obstacle / remove_obstacle

Place test objects: cylinder, ball, box or wall, with size and color

add_color_tape / remove_color_tape

Colored floor tape for the color sensor, line following and the camera

Example prompts: "Open the rover simulator and drive it to the light without using the autopilot", "Add an IR sensor on each side angled ±45° and tell me the readings", "What parts do I need to build this rover on an ESP32?"

Configuration

  • ROVER_BRIDGE_PORT (default 8765). If you change it, the page needs ?mcpPort=<port> (open_simulator adds this for you).

  • ROVER_SIMULATOR_URL: the page open_simulator opens instead of the hosted one. A URL (http://localhost:5173 while developing) or a path to a local build (dist/index.html, relative to the working directory).

  • ROVER_ALLOWED_ORIGINS: extra comma-separated https:// origins the bridge accepts (for a self-hosted copy of the simulator).

  • On the page: ?mcp=on connects to the server, ?mcp=off never does.

Security

The WebSocket listens on 127.0.0.1 only. It accepts connections only from the page opened from disk (file://), from localhost, from the hosted simulator, or from the origin of ROVER_SIMULATOR_URL / ROVER_ALLOWED_ORIGINS, so other websites open in the same browser cannot pose as the rover. The page only runs the fixed set of methods listed above; it never evaluates code it receives from the server, except the program you send with run_program, which runs in a Web Worker.

License

MIT

Available Tools

41 tools
add_color_tapeAdd colored floor tapeA

Stick a strip of colored tape on the floor (for the color sensor, line following and the camera). A color sensor over the tape reads its color name.

Inputs: x (required), y (required), color (required), angle, +2 more.

add_obstacleAdd obstacleA

Place an object in the world to test sensors, collisions or the camera. Kinds: cylinder / ball (circle, radius r), box / wall (rectangle w × h, rotated by angle°). Unspecified size and color use the kind's defaults. Refused if it would overlap the rover.

Inputs: x (required), y (required), kind (required), h, +4 more.

add_sensorAdd sensorB

Install a new sensor on the rover body. Unspecified fields use the type defaults (centre of the body, facing forward).

Inputs: type (required), x, y, name, +3 more.

capture_cameraCapture camera imageA
Read-only

Take a picture with the rover's forward-facing camera (needs the camera module). Returns a 320×240 first-person PNG (walls, colored obstacles, colored floor tape, the light source) and a JSON list of what is in view: type (obstacle / tape / light), id, color, bearing_deg (0 = straight ahead, + = right) and distance_cm.

Inputs: fov_deg.

connection_statusConnection statusB
Read-only

Report whether the simulator page is connected to this MCP server.

Inputs: no named parameters.

display_textShow text on the displayA

Make the rover "say" a text on the Face Display module (128×64 OLED): a small rover face with a talking mouth and the text typed out in a speech bubble (Thai supported, ~11 characters per line, 2 lines per bubble, extra bubbles follow). Returns to the big face after seconds, or once every bubble has been shown if that takes longer.

Inputs: text (required), seconds.

draw_displayDraw a picture on the displayA

Show a picture on the Face Display module for seconds, then return to the face. Pass one string per pixel row, at most the module's resolution (SSD1306 128×64, SSD1331 96×64, ST7789 240×240; see read_display). Characters space . 0 - _ are dark. On colour modules (SSD1331, ST7789) these letters pick a colour: R red, O orange, Y yellow, G green, C cyan, B blue, P purple, M pink, W white, A grey, N brown, K black; any other character is white, and palette adds or overrides letters. On the monochrome SSD1306 every non-blank, non-black character is a lit pixel and colour comes from its panel variant (panel). The picture is centred; scale enlarges each pixel (e.g. 64×32 with scale 2 fills 128×64) and is lowered if it would not fit. Returns read_display, so the result shows what the module actually displays.

Inputs: rows (required), panel, scale, palette, +1 more.

driveDriveA

Move the rover for a fixed time: forward / backward, or turn left / right in place. Turns autopilot off and starts the simulation. Rotation speed is about 2 rad/s (≈115°/s), so turning 90° takes ≈0.8 s. Forward speed is 65 % of max speed (≈61 px/s at the default 55 % power; backward ≈51 px/s). With wait=true (default) it returns the observation after the move finishes. The rover stops on collisions.

Inputs: direction (required), wait, seconds.

get_bomGet parts listA

Bill of materials for building the fitted rover body for real (the parts tab on the Wiring page): the board, motor driver, every enabled sensor, display, camera and head servo, plus the parts the circuit needs around them (chassis, battery, buck converter, voltage-divider resistors, level shifter …), each with quantity, approximate price in THB and shop links when known, and a plain-text list to copy. board switches the board first: "esp32", "uno" or "raspberrypi".

Inputs: board.

get_button_eventsButton eventsA

Button presses since the last call (oldest first, then cleared): { id, name, press: "short" | "long", seconds, at (ms epoch) }, plus every button and whether it is held right now. People press buttons in the simulator page; poll this to react to them.

Inputs: no named parameters.

get_firmwareGet firmwareA

A complete program for the real robot, generated from the fitted body and the wiring pin map: an Arduino sketch (rover_firmware.ino) for "esp32" / "uno", or a Python script (rover.py) for "raspberrypi". It drives the TB6612FNG wheels, reads every enabled sensor, turns the head servo (with light tracking), draws faces on the display and runs the same auto emotions / rule-based autopilot as the simulator. Text commands over Serial 115200 / stdin: READ, F|B|L|R , AUTO 0|1, POWER <%>, HEAD , TRACK 0|1, EMO [text], SAY , STOP. Returns { name, text }. board switches the board first.

Inputs: board.

get_headHead statusA
Read-only

Head module status: angle_deg, target_deg, mode (manual / track_light), tracking phase and the head light brightness.

Inputs: no named parameters.

get_manifestGet robot manifestB
Read-only

The Robot Capability Manifest (ai-cartridge/body-v1): motors, installed sensor modules and display.

Inputs: no named parameters.

get_observationGet observationA
Read-only

Current robot pose (x, y, heading_deg), velocity, every enabled sensor reading, face display state, plus simulation status (running, autopilot, power, lamp position).

Inputs: no named parameters.

get_programProgram statusA
Read-only

The current/last rover program: code, status (idle, running, listening, done, stopped, error), error { message, line } and the last 50 console lines.

Inputs: no named parameters.

get_sensor_mapGet sensor mapA

The map the rover has built from its own sensors only (not the true layout): an occupancy grid of 10 px cells as ASCII rows ("#" occupied by a sonar/IR echo or bumper hit, "." free, " " unknown, "@" rover, a capital letter = floor color read by a color sensor), camera landmarks with estimated world x/y, bumper hit points, the pose and exploration stats. clear=true wipes the map first.

Inputs: clear.

get_wiringGet wiringA

How the fitted rover body wires to a real microcontroller (the Wiring page): for each part (TB6612FNG motor driver, each enabled sensor, the display module, the camera) every pin and where it goes (MCU pin or 5V / 3V3 / GND / VBAT rail), the power budget per rail, issues found (pin conflicts, missing pins, 5 V signals into 3.3 V pins, duplicate I²C addresses, ESP32 strapping / ADC2 pins) and a ready-to-use pin file (Arduino pins.h, or pins.py with BCM numbers on the Pi). board switches the board first: "esp32" (ESP32 DevKit V1), "uno" (Arduino Uno R3) or "raspberrypi" (Raspberry Pi 4/5 40-pin header; analog sensors go through an ADS1115 on I²C, the camera on the CSI ribbon).

Inputs: board.

list_sensorsList sensorsA
Read-only

All configured sensors (enabled or not) with id, type, mounting position, angle and range.

Inputs: no named parameters.

list_worldList world layoutB
Read-only

World size, light position, all obstacles (id, kind, shape, position, size, color) and colored floor tapes.

Inputs: no named parameters.

move_lightMove light sourceB
Idempotent

Move the light source to world coordinates (clamped to 42–758 × 42–478).

Inputs: x (required), y (required).

open_simulatorOpen simulatorA

Open the AI Rover Studio page in the default browser and wait (up to 15 s) for it to connect to this MCP server.

Inputs: no named parameters.

press_buttonPress a buttonA

Press a push-button module (a sensor of type "button") for seconds and release it, like a person would. Held ≥ 0.8 s is a long press. The built-in program reacts: short press toggles the head's light tracking (happy face), long press stops everything (driving, autopilot, tracking; pauses the simulation). Returns the press event.

Inputs: id (required), seconds.

read_displayRead the displayA
Read-only

Read back what the Face Display module is showing: mode (face/text), text lines, module stats (frames, fps, bytes) and the actual 128×64 pixels from the module's GDDRAM as ASCII art (█▀▄, 2 pixel rows per line).

Inputs: no named parameters.

read_sensorsRead sensorsA
Read-only

Fresh readings from all enabled sensors, with their mounting position, angle, range and unit.

Inputs: no named parameters.

remove_color_tapeRemove colored floor tapeB
Destructive

Remove a floor tape by id (see list_world).

Inputs: id (required).

remove_obstacleRemove obstacleB
Destructive

Remove an obstacle by id (see list_world).

Inputs: id (required).

remove_sensorRemove sensorC
Destructive

Uninstall a sensor by id.

Inputs: id (required).

reset_worldReset worldA
Idempotent

Put the rover back at its start pose (120, 265, heading 0°) and the light at (690, 70). Turns autopilot off.

Inputs: no named parameters.

run_programRun a rover programA

Run JavaScript on the robot with the rover library (same as the Code page; it replaces any running program and starts the simulation). Top-level await works. Motion (await): rover.forward(s), backward(s), turn(deg), left(s), right(s); rover.drive(speed −1…1, turn °/s) keeps going; rover.stop(); rover.power(%). Readings (sync, 50 ms snapshots): rover.read(id), sensors(), distance() (nearest sonar/IR cm), light() (%), bumped(), pose(), time(). Head/face: await rover.head(deg), trackLight(on), headAngle(); rover.face(emotion, text), say(text, s). Buttons: pressed(id), onButton([id], fn(event)), await waitButton([id]). Time/output: await wait(s), await rover.until(fn, timeout), log(...). Customise: await rover.module(name, on), addSensor({type,name,x,y,angle,range}), updateSensor(id, fields), removeSensor(id), sensorList(). Returns immediately; poll get_program for status and the console.

Inputs: code (required).

send_chatSend chat commandA

Send a message to the in-page Agent Chat (offline Thai/English command parser, e.g. "ไปหาแสง", "อ่านเซนเซอร์", "เดินหน้า 2 วินาที") and return the rover's reply. It shows up in the chat panel.

Inputs: text (required).

set_autopilotAutopilotA
Idempotent

Enable the built-in rule-based autopilot (seeks the light, backs away from obstacles; also starts the simulation) or disable it.

Inputs: enabled (required).

set_displayChoose the display moduleA
Idempotent

Fit a different Face Display module: "ssd1306" (0.96" 128×64 monochrome OLED, I²C; default), "ssd1331" (0.95" 96×64 colour RGB OLED, SPI) or "st7789" (1.3" 240×240 colour IPS TFT, SPI). Faces and text adapt to the resolution; colour modules show a colour per emotion. panel changes the SSD1306 glass colour. Returns read_display.

Inputs: model, panel.

set_emotionFace expressionA

Show an expression on the robot's face display (emulated SSD1306 128×64 OLED); the message appears in the top text line and scrolls if long. Held ~5 s before sensor-driven emotions resume.

Inputs: emotion (required), message.

set_headTurn the headA

Control the Head module (pan servo, needs set_module head first). angle_deg turns the face to −90…90° relative to the body (+ = right, servo ≈180°/s) and switches to manual. track_light=true makes the head find and follow the light with its own light sensors: it sweeps the full range, settles on the brightest angle and keeps hill-climbing (rescans if the light is lost). Light sensors are directional (brightest when facing the lamp) and ride on the head. Starts the simulation.

Inputs: angle_deg, track_light.

set_moduleInstall / remove a moduleA
Idempotent

Install or remove a body module: "wheels" (drive motors + wheels; without them the rover cannot move), "head" (pan servo that turns the face and the light sensors), "display" (AI Face Display OLED) or "camera" (forward-facing camera).

Inputs: module (required), installed (required).

set_powerMotor powerA
Idempotent

Set motor power in percent (10–100). Max speed is 170 px/s at 100 % (drive uses 65 % of it forward, 55 % backward).

Inputs: percent (required).

set_simulationStart / pause simulationA
Idempotent

Start (running=true) or pause (running=false) the physics simulation.

Inputs: running (required).

stopStopA
Idempotent

Emergency stop: cancel any movement, turn autopilot off and pause the simulation.

Inputs: no named parameters.

stop_programStop the programA
Idempotent

Stop the running rover program (its worker is terminated, the wheels stop).

Inputs: no named parameters.

turnTurn by degreesA

Turn the rover in place by an exact angle (+ = right / clockwise, − = left) at ≈115°/s, then return the observation. Unlike drive left/right there is no 0.2 s minimum, so small corrections (e.g. 7°) are exact.

Inputs: degrees (required).

update_sensorUpdate sensorB

Change a sensor's name, type, mounting position, angle, range or enabled flag. Use list_sensors to find ids.

Inputs: id (required), x, y, name, +4 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 41 tools

    Disambiguation4/5

    Most tools have clearly distinct resource/action boundaries, and the descriptions disambiguate subtle pairs such as read_sensors vs get_observation and set_emotion vs display_text. Some overlap remains among the face/display tools and among stop, stop_program, and pausing the simulation, which could cause occasional misselection.

    Naming Consistency4/5

    The surface is predominantly consistent snake_case with verb_noun names like list_sensors, add_obstacle, and get_wiring. Minor deviations such as the bare verbs drive, turn, stop, and state-style names like connection_status keep it from being perfect, but the pattern remains predictable.

    Tool Count2/5

    With 41 tools, the server is far above the typical well-scoped range and creates significant selection overhead for an agent. The simulator is genuinely broad, so many tools earn their place, but the overall surface is too large for comfortable tool selection.

    Completeness5/5

    The set covers an unusually full lifecycle: simulation control, movement, sensor CRUD, obstacles, floor tape, display output, programs, camera, buttons, wiring, BOM, and firmware generation. No obvious operational dead ends are apparent for the stated robotics-simulator domain.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables real-time monitoring and control of any Webots robot simulation, providing access to robot state, sensors, camera feeds, and simulation controls (pause, resume, reset) through natural language.
      1
      -
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI assistants to build and simulate Tinkercad Circuits through a real Chrome session, including placing parts, wiring pins, writing Arduino code, running simulations, and reading serial output.
      4
      17
      65 npm
      3
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables an LLM agent to assemble, wire, run, fault and observe electromechanical motor-control circuits through 26 tools covering component placement, terminal connections, button/switch operation, fault injection, and simulation control. Also lets agents load and save circuits and generate PDF drawing sets, screenshots and scripted demo videos.
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to drive a browser-based game editor directly, covering projects, entities, scripts, assets, templates, animation, scenes, settings, builds, and viewport and runtime control. Agents can also launch the project and verify it actually runs by capturing screenshots, logs, and live state, then send keyboard, mouse, and touch input.
      -