EV3 MCP Server

Host-side FastMCP stdio server that any MCP client can use to drive a LEGO Mindstorms EV3 over Wi-Fi SSH. MCP stays on your Mac; only thin ev3dev2 Python runs on the brick.

This repo also includes a CLI chat client that uses Hugging Face Inference Providers (OpenAI-compatible) by default, spawns the local EV3 MCP server, and lets you type natural language like move forward.

Architecture

CLI chat (ev3-chat / main.py)  or  Cursor / Claude Desktop
        │ stdio MCP tools
        ▼
ev3_mcp on Mac  ──persistent SSH──►  EV3 brick (ev3dev2 motors)

Requirements

• Python 3.10+
• uv (recommended)
• EV3 running ev3dev with python3-ev3dev2
• SSH reachability from the host (password auth by default)
• For the chat CLI: a Hugging Face token with Inference Providers permission (or any OpenAI-compatible endpoint)

Setup

cd /path/to/ev3dev_MCP
uv sync
cp .env.example .env   # edit only when leaving dry-run / set LLM vars for chat

Dry-run is on by default (EV3_DRY_RUN=1): no SSH is opened at startup or on tool calls; tools log the would-be remote Python and return fake success shaped like real results. Flip to EV3_DRY_RUN=0 only after EV3_HOST is reachable and EV3_PASSWORD works.

When dry-run is off, the MCP server connects over SSH immediately on startup (eager connect) and logs success or failure. Tool calls still reconnect if the session drops.

Auth

Method	Env	Notes
Password (primary)	EV3_PASSWORD	Default path — set this in .env
SSH key (optional fallback)	EV3_SSH_KEY_PATH (default ~/.ssh/id_ev3)	Used only when EV3_PASSWORD is unset

Never commit a real .env.

Motors / safety

Variable	Default	Purpose
EV3_LEFT_MOTOR / EV3_RIGHT_MOTOR	B / C	Tank drive ports
EV3_DEFAULT_SPEED / EV3_MAX_SPEED	40 / 80	Default and clamp for speed_pct
EV3_DEFAULT_DURATION / EV3_MAX_DURATION	1.0 / 5.0	Default and clamp for duration_s

Drive tools use timed on_for_seconds runs (not infinite spin). Concurrent drive calls are rejected as busy; stop bypasses the lock and clears it.

Run the MCP server

# stdio MCP server (what clients spawn)
uv run python -m ev3_mcp.server

# or after uv sync / pip install -e .
python -m ev3_mcp.server

Run the CLI chat client

The client spawns ev3_mcp.server over stdio, calls a chat model via Hugging Face’s OpenAI-compatible router, and runs a prompt-toolkit chat loop.

# 1. Put HF_TOKEN in .env (https://huggingface.co/settings/tokens)
# 2. Pick a tool-capable OPENAI_MODEL, then:

uv run main.py
# or
uv run ev3-chat
# or
uv run python -m ev3_chat

Optional extra MCP server scripts (same pattern as the reference cli_project):

uv run main.py /path/to/other_mcp_server.py

Chat client env

Variable	Default	Purpose
HF_TOKEN	(required)	Hugging Face token (Inference Providers). Also accepts OPENAI_API_KEY.
OPENAI_BASE_URL	https://router.huggingface.co/v1	HF router; set to http://127.0.0.1:1234/v1 for LM Studio
OPENAI_MODEL	meta-llama/Llama-3.3-70B-Instruct	Tool-capable model id (model or model:provider)
USE_UV	1	Spawn EV3 server with uv run when 1

Tool calling: the EV3 tools only work if the model/provider supports OpenAI-style tools. Prefer instruct models known for function calling; you can append :fastest, :cheapest, or a provider like :groq / :together.

Smoke-test MCP only (no LLM required) — lists the 7 EV3 tools:

uv run mcp_client.py
# or
uv run python -c "from ev3_chat.mcp_client import main; import asyncio; asyncio.run(main())"

Tools

Tool	Behavior
move_forward	Both motors forward for duration_s / speed_pct
move_backward	Same, reverse
turn_left / turn_right	Differential turn
stop	Immediate stop — bypasses command lock
beep	Speaker beep
list_connected_devices	Live motors/sensors on the brick (address, driver, mode)
robot_status	Dry-run flag, SSH state, ports, busy, last error

Client wiring

Cursor / Claude Desktop

Copy from mcp.json.example. Point command/args at this repo and set env (keep dry-run until the brick is ready):

{
  "mcpServers": {
    "ev3": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/ev3dev_MCP", "python", "-m", "ev3_mcp.server"],
      "env": {
        "EV3_DRY_RUN": "1",
        "EV3_HOST": "192.168.1.100",
        "EV3_USER": "robot",
        "EV3_PASSWORD": "maker"
      }
    }
  }
}

Claude Desktop uses the same stdio shape in claude_desktop_config.json.

Constraint

The MCP process must run on a machine that can SSH to the EV3 (typically your Mac on the same Wi-Fi). Cloud-only agents that cannot spawn a local stdio server cannot drive the brick in v1.

Layout

Path	Role
src/ev3_mcp/	FastMCP stdio server
src/ev3_chat/	CLI chat client (mcp_client, core/*, main)
main.py	Thin entry → ev3_chat.main (uv run main.py)
mcp_client.py	Thin smoke-test entry (list tools, no LLM)

Out of scope (v2)

Sensors, camera, on-brick MCP, persistent brick daemon, drive-command queuing, SSE/HTTP remote MCP.