lerobot-mcp

MCP server for LeRobot workflows.

lerobot-mcp gives MCP clients a structured, auditable interface over the current LeRobot CLI, examples, source registries, datasets, and dataset conversion workflows.

Features

• Discover available lerobot-* entry points from a managed, local, or installed LeRobot checkout.
• List and run scripts under LeRobot's examples/ tree with path traversal protection.
• Audit registered policies, rewards, robots, teleoperators, cameras, envs, processors, rollout

strategies, optimizers, schedulers, and RL algorithms by static source inspection.

• Build dry-run LeRobot commands from structured MCP arguments.
• Run LeRobot commands as foreground calls or managed background jobs.
• Inspect LeRobot dataset metadata without importing heavy robotics dependencies at MCP startup.
• Inspect policy/model repo metadata for observation, image, state, and action contract hints.
• Optionally use Hub auth from your existing environment.
• Convert robotics datasets into LeRobot-compatible formats.
• Search datasets by robot, format, task, size, episode count, and compatibility hints.

Install

From PyPI:

uv tool install lerobot-mcp

From a checkout:

git clone https://github.com/noah-wardlow/lerobot-mcp.git
cd lerobot-mcp
uv sync --extra dev

MCP Quick Start

Most users should use the LeRobot checkout they already have. Start your MCP client from inside that checkout, set LEROBOT_ROOT=/path/to/lerobot in the MCP server environment, or ask the agent to find and select a checkout with lerobot_find_lerobot_roots and lerobot_use_lerobot_root.

If no checkout is found, LeRobot-backed tools lazily prepare a managed fallback at ~/.cache/lerobot-mcp/lerobot with Python 3.12 and LeRobot's dataset extra. That fallback covers dataset metadata, format conversion, and common command help without requiring a separate setup step.

Advanced install controls:

• Set LEROBOT_ROOT=/path/to/lerobot to use a specific checkout.
• Set LEROBOT_MCP_LEROBOT_PYTHON=3.13 to use a different Python when preparing the managed

fallback.

• Set LEROBOT_MCP_LEROBOT_EXTRAS=dataset,core_scripts to install more LeRobot extras by default.
• Set LEROBOT_MCP_AUTO_SETUP=0 to disable the managed fallback.

Codex

Recommended:

codex mcp add lerobot-mcp -- lerobot-mcp

Manual fallback:

[mcp_servers.lerobot_mcp]
command = "lerobot-mcp"
startup_timeout_sec = 20
tool_timeout_sec = 3600

Restart Codex, run /mcp, then ask: "List LeRobot commands."

Claude Code

claude mcp add lerobot-mcp -- lerobot-mcp

From a checkout:

claude mcp add lerobot-mcp -- /path/to/lerobot-mcp/.venv/bin/lerobot-mcp

Restart Claude Code, run /mcp, then ask: "Show lerobot_capabilities."

Resolution order is: LEROBOT_ROOT, current project ancestors, managed checkout ~/.cache/lerobot-mcp/lerobot, ~/hrl/lerobot, then an installed lerobot package.

Tool Model

The server does not expose arbitrary shell execution. It only runs:

• LeRobot entry points discovered from the configured checkout or installed distribution, such as

lerobot-train, lerobot-eval, lerobot-record, lerobot-replay, lerobot-annotate, lerobot-rollout, and hardware setup utilities.

• Python scripts inside the configured LeRobot checkout's examples/ directory.
• Dataset conversion helpers exposed by this MCP server.

Options are passed as structured key/value pairs and serialized to draccus-compatible arguments:

{
  "command": "train",
  "options": {
    "policy.type": "act",
    "dataset.repo_id": "lerobot/aloha_mobile_cabinet"
  }
}

That becomes:

uv run lerobot-train --dataset.repo_id=lerobot/aloha_mobile_cabinet --policy.type=act

Main MCP Tools

• lerobot_server_config: show resolved LeRobot root, uv usage, and managed Python/extras.
• lerobot_find_lerobot_roots, lerobot_use_lerobot_root: find an existing LeRobot checkout and use

it for the current MCP session.

• lerobot_install_or_update_lerobot: clone or update LeRobot main into the managed checkout and

prepare its uv environment.

• lerobot_list_commands: list discovered LeRobot console scripts.
• lerobot_capabilities: audit current LeRobot commands, extras, examples, and registered components.
• lerobot_command_help: run --help for a discovered LeRobot command.
• lerobot_list_examples: list runnable examples in the checkout.
• lerobot_build_command: dry-run a command from structured options.
• lerobot_run_command: run a known LeRobot entry point.
• lerobot_run_example: run an example script under examples/.
• lerobot_list_jobs, lerobot_job_status, lerobot_job_logs, lerobot_cancel_job: manage

background jobs.

• lerobot_inspect_dataset_metadata: summarize metadata for a local or Hub dataset.
• lerobot_hf_search_datasets: search datasets by robot, format, size, task, tags, and demo fit.
• lerobot_inspect_policy_repo: inspect a Hugging Face policy/model repo for config files, weights,

policy type, dataset/robot hints, FPS, and declared observation/action features.

• lerobot_convert_dataset_to_latest_format: convert LeRobot v2.1 datasets to the current v3.0

parquet layout.

LeRobot Dataset Format Migration

Latest LeRobot main currently uses the v3.0 parquet layout. The upstream converter supports v2.1 datasets and rewrites them to:

• data/chunk-*/file_*.parquet
• videos/<camera>/chunk-*/file_*.mp4
• meta/tasks.parquet
• meta/episodes/chunk-*/file_*.parquet
• aggregate meta/stats.json, with per-episode stats flattened into the episode parquet metadata

Preview a conversion:

{
  "repo_id": "lerobot/berkeley_autolab_ur5",
  "root": "/tmp/berkeley_autolab_ur5",
  "force_conversion": true
}

Run it as a background job:

{
  "repo_id": "lerobot/berkeley_autolab_ur5",
  "root": "/tmp/berkeley_autolab_ur5",
  "force_conversion": true,
  "background": true,
  "push_to_hub": false
}

push_to_hub defaults to false. For Hub datasets that already have a v3.0 tag, omit force_conversion to let the upstream script reuse the latest compatible version. Older branches such as v1.x or v2.0 need to be brought to v2.1 before using this converter.

Dataset Search

Search is intended to help a user find datasets that fit their robot, computer, and target format. It can combine Hub results with locally configured registry metadata.

Example MCP arguments:

{
  "query": "pusht",
  "robot": "aloha",
  "format": "lerobot",
  "max_size_gb": 10,
  "demo_suitable": true,
  "sort": "lastModified",
  "limit": 5
}

Results include source, repo id, detected format, robot hints, tags, scale when known, popularity signals, and conversion hints.

For offline or deterministic tests, set FORGE_REGISTRY_PATH to a local datasets.json registry.

Policy Repo Inspection

Use policy inspection before wiring a real browser or simulator rollout. It does not import LeRobot or run inference; it reads Hub repo metadata and lightweight JSON config files.

Example MCP arguments:

{
  "repo_id": "username/my-policy",
  "include_raw_configs": false
}

The result includes config/weight file presence, policy type, dataset and robot hints, FPS, declared input/output features, and classified image_keys, state_keys, and action_keys. Clients can use that to map camera captures and state vectors before starting an inference server.

Development

uv sync --extra dev
uv run ruff check .
uv run mypy
uv run pytest -vv

Run against latest LeRobot main:

cd /path/to/lerobot
git checkout main
git pull --ff-only origin main

cd /path/to/lerobot-mcp
LEROBOT_ROOT=/path/to/lerobot uv run lerobot-mcp

Build the package:

uv build

This repository is Apache-2.0 licensed.