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)

Related MCP server: mcp-ssh-tool

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

Never commit a real .env.

Motors / safety

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

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

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

Out of scope (v2)

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