v1 Scout / datasheet Install

Gekko

Gekko v1 “Scout” Model Context Protocol server for microcontrollers mygekko.si

Your AI assistant, plugged into the board.

Gekko runs on your own computer and gives your assistant hands on the microcontrollers plugged in over USB. It finds the board, talks to it, builds and flashes the firmware, and checks the wiring before anything is powered.

Install See the tools
1Description

A small local server that gives the assistant hands.

Gekko is a Model Context Protocol (MCP) server. Your assistant talks to it, and it talks to the boards on your USB ports: Raspberry Pi Pico and Pico W, ESP32, ESP32-S3, Arduino Uno and Nano.

Before anything is powered, it checks pins and wiring against a database of boards and components.

It never changes a board without your OK.

Flashing, resetting, entering the bootloader and writing files all wait for you to say yes.

Features

  • Finds boards by USB id
  • Reads and writes the serial port
  • Runs MicroPython through the raw REPL
  • Builds with arduino-cli, PlatformIO or MicroPython, and flashes with one call
  • Decodes ESP32 crashes into function names and lines
  • Checks pins and wiring against a board and component database
  • Shows every call as it runs in Gekko Live
  • Never changes a board without your OK
Functional block diagram: the AI assistant talks MCP to Gekko on your computer. Gekko talks USB serial to the board, streams every call to Gekko Live, and sets boards up on the IoT hub, which then reaches them over TLS. MCP every call USB serial iot TLS AI assistant Claude Code, Claude Desktop, Cursor, VS Code Gekko MCP server, on your computer Gekko Live 127.0.0.1 Board Pico, ESP32 IoT hub internet
Figure 1. Functional block diagram. Solid lines run on your desk; dashed lines go over the internet.
2Typical application: a real conversation

A restart loop, diagnosed from one sentence.

A real exchange. The assistant doesn’t guess: it asks Gekko to read the boot log on the board’s port, then explains what it found in plain words.

Transcript ESP32 on COM5
  1. you

    my esp32 keeps restarting when the servo moves

  2. tool

    detect_reset_reason port COM5, capture 5 s

  3. result
    reason
    brownout
    evidence
    “Brownout detector was triggered”
    restarts
    3 in 5.0 s
    rst
    0xf RTCWDT_BROWN_OUT_RESET
  4. assistant

    The board isn’t crashing, it’s losing power. Each time the servo starts it pulls a current spike that drags the 3.3 V rail under the brownout limit. Give the servo its own 5 V supply, join the grounds, and put a 470 µF capacitor across the servo rail.

Figure 2. A restart loop on an ESP32. One tool call, five seconds of boot log, one answer.
3Pin functions: the 24 tools

Twenty-four tools, one job each.

Gekko is one server with 24 tools in six groups. Each does a single thing and hands back a result the assistant can act on. Twenty-four is also exactly a DIP-24, so here they are as a package.

Pin configuration: Gekko's 24 tools drawn as the pins of a 24-pin dual in-line package, pin 1 top left. gekko-mcp · v1 Scout 1list_devices 2serial_open 3serial_read 4serial_write 5serial_close 6serial_capture 7repl_exec 8device_fs 9device_reset 10enter_bootloader 11build 12flash 13resolve_board 14lib_search 15lib_install 16lib_check 17decode_backtrace 18detect_reset_reason 19pin_check 20wiring_validate 21live_view 22panel 23iot 24doctor Pin configuration: Gekko's 24 tools drawn as the pins of a 24-pin dual in-line package, pin 1 top left. gekko-mcp · v1 Scout 1list_devices 2serial_open 3serial_read 4serial_write 5serial_close 6serial_capture 7repl_exec 8device_fs 9device_reset 10enter_bootloader 11build 12flash 13resolve_board 14lib_search 15lib_install 16lib_check 17decode_backtrace 18detect_reset_reason 19pin_check 20wiring_validate 21live_view 22panel 23iot 24doctor
Figure 3. Pin configuration, top view. Hover a pin or a row, or step through Table 1 with the arrow keys, to find its partner.Table 1 below lists the same pins by number.
Table 1. Pin functions. “Your OK” marks the calls Gekko asks you about before it runs them. Where only part of a call writes to the board, it names that part.
PinNameFunctionYour OK
Device I/O 10 · pins 1–10
1list_devicesFinds boards by USB id.
2serial_openOpens a serial session and buffers everything the board sends.
3serial_readReads buffered output, optionally waiting for a text or regex match.
4serial_writeSends text to an open serial session.
5serial_closeCloses the session and frees the port.
6serial_captureRecords N seconds of output and summarises the numbers.
7repl_execRuns MicroPython through the raw REPL.
8device_fsls, get, put and rm on the board’s files.put, rm
9device_resetHardware reset through DTR/RTS, or a MicroPython soft/hard reset.required
10enter_bootloaderESP32 download mode or Pico BOOTSEL, without pressing buttons.required
Build and flash 6 · pins 11–16
11buildarduino-cli, PlatformIO or MicroPython; errors come back as file, line, message.
12flashesptool, UF2 copy, picotool and avrdude behind one call.required
13resolve_boardTurns a board name or alias into its exact id, toolchain settings and flashing method.
14lib_searchSearches the Arduino library index or MicroPython packages, for example for a missing header.
15lib_installInstalls a library found with lib_search.MicroPython
16lib_checkWorks out the library every part needs and installs what is missing.install
Debug 2 · pins 17–18
17decode_backtraceTurns an ESP32 panic into function names and lines.
18detect_reset_reasonReads brownout, watchdog or panic from the boot log.
Hardware checks 2 · pins 19–20
19pin_checkStrapping pins, input-only pins, ADC2 with Wi-Fi.
20wiring_validate5 V into 3.3 V, missing pull-ups, supply and current budgets.
Live and control 3 · pins 21–23
21live_viewOpens Gekko Live.
22panelPuts controls and readouts on a grid.
23iotSets a board up on the Gekko IoT hub and sends it commands.provision
Setup 1 · pin 24
24doctorShows which toolchains are installed and how to add the missing ones.
4Wiring check: before power-on

It checks the wiring before you power on.

An HC-SR04 runs on 5 V, so its ECHO pin answers with 5 V. An ESP32 GPIO is a 3.3 V pin and not 5 V tolerant. Wire one straight to the other and that is exactly the mismatch wiring_validate catches, on paper, before anything is powered.

HC-SR04 wired to an ESP32 DevKit V1 VCC to VIN, TRIG to GPIO25, ECHO to GPIO18, GND to GND. As wired, ECHO puts 5 V on GPIO18, a 3.3 V pin that is not 5 V tolerant. With a 1k and 2k divider on ECHO, GPIO18 sees 3.33 V. R1 1k R2 2k 5 V 5.00 V 3.3 V logic U1 · HC-SR04 VCCTRIGECHOGND VINGPIO25GPIO18GND ESP32 DevKit V1 esp32_devkit, 3.3 V logic
Figure 4. U1 on an ESP32 DevKit V1. As wired, ECHO drives GPIO18 at 5.00 V. A 1k/2k divider brings it down: 5 V × 2k / (1k + 2k) = 3.33 V.
wiring_validateok: false · 1 error
board
esp32_devkit
part
U1 hc-sr04
VCC
→ VIN
GND
→ GND
TRIG
→ GPIO25
ECHO
→ GPIO18
ECHO
→ 1k/2k divider → GPIO18
error
level_mismatch
ECHO drives GPIO18 to 5 V; the ESP32’s GPIOs are 3.3 V and not 5 V tolerant
fix
1k/2k divider on ECHO → 3.33 V
or a BSS138 level shifter
info
level_divider
GPIO18 gets 3.33 V through the divider: within the 3.3 V logic level
rail
5V  20 mA of 500 mA
ok
false, 1 error
ok
true, 0 errors

The checks come from a database of boards and components, not from a guess, so the same wiring always gets the same answer. pin_check does the same for single pins: strapping pins, input-only pins, ADC2 while Wi-Fi is on.

5Gekko Live: watch every call

Watch it work.

Gekko Live is a local page at 127.0.0.1 that follows every tool call as it runs. Nothing the assistant does to your board happens out of sight.

What it shows

BoardDrawn with its state: flashing, running code, in the bootloader
ProgressThe steps of the call and a progress bar
SerialThe bytes going to and from the board
ResultThe exact raw result the AI received

The Panel tab

A dotted grid where the assistant places controls wired to the board. Drag them to rearrange. Every number the board prints shows up under Readings.

Controls 7colour picker, slider, toggle, button, number field, option picker, XY pad
Readouts 5value, gauge, graph, LED, log
Panel127.0.0.1
gauge 50%
graphhistory
toggle
LED
Figure 5. A sketch of the Panel tab, not a screenshot. Move the slider and the gauge and graph follow; the toggle switches the LED and the colour picker sets its colour.
6Remote control: the IoT hub

Beyond the cable.

The iot tool sets a Wi-Fi board, a Pico W for example, up on the Gekko IoT hub over the USB cable. After that, the assistant and a web dashboard control it over the internet.

The dashboard shows

  • Which boards are online
  • Readings, with history charts
  • Editable controls
  • Every command, with how long it took to arrive
Open the IoT dashboard
Timing: a command sent by the assistant or the dashboard arrives at the board about 0.1 seconds later. Command sent assistant or dashboard Command arrives board, over TLS ≈ 0.1 s
Figure 6. Command delivery timing. Not to scale.
Table 2. Remote link characteristics
ParameterConditionsValue
Setup linkfirst time, by the iot toolUSB cable
Control linkafterwards, assistant and dashboardinternet
Transportconnection to the boardverified TLS
Command deliveryto the board≈ 0.1 s
7Supported boards: chips and voltages

Six boards, two logic levels.

Gekko knows each of these boards: the chip on it, the voltage on its pins and how to get firmware onto it.

Table 3. Electrical characteristics and toolchains
BoardMCULogic levelFlashingFrameworks
Raspberry Pi PicoRP20403.3 VUF2, picotoolMicroPython, Arduino
Raspberry Pi Pico WRP2040 + CYW433.3 VUF2, picotoolMicroPython, Arduino
ESP32 DevKit V1ESP32-WROOM-323.3 VesptoolMicroPython, Arduino, PlatformIO
ESP32-S3-DevKitC-1ESP32-S33.3 VesptoolMicroPython, Arduino, PlatformIO
Arduino Uno R3ATmega328P5 VavrdudeArduino, PlatformIO
Arduino NanoATmega328P5 VavrdudeArduino, PlatformIO

Mixing the two levels is where boards get hurt: a 5 V signal on a 3.3 V pin is exactly what wiring_validate flags (section 4).

8Installation: three steps

Three steps, then ask what’s connected.

Status

Gekko v1 is in development. It installs from source today; the PyPI package, which makes step 02 a one-liner, is planned.

  1. 01

    Get uv

    uv runs Gekko and its Python dependencies.

    winget install astral-sh.uv
  2. 02

    Add Gekko to your assistant

    From source, today:

    claude mcp add gekko -- uv --directory /path/to/gekko-mcp run gekko-mcp

    Once it is on PyPI:

    claude mcp add gekko -- uvx gekko-mcp

    That command is for Claude Code. Claude Desktop, Cursor, VS Code and other MCP clients take the part after -- as a server entry in their JSON settings: "command" is uv (or uvx), and the rest goes in "args". Claude Desktop also needs GEKKO_WORKSPACE set to your project folder.

  3. 03

    Plug in a board and ask

    “what’s connected?”

    Gekko finds it by USB id and Gekko Live opens at the first hardware call.