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. Gekko is drawn as a 24-pin package, one pin per tool. Solid lines stay on your desk: MCP between the assistant and Gekko, USB serial between Gekko and the board, and every call to Gekko Live at 127.0.0.1. Dashed lines go over the internet: from Gekko to the IoT hub, and from the hub to the board over TLS. When motion is on, the drawing plays three calls in turn: detect_reset_reason reads the boot log over USB and returns brownout; flash waits for your OK before it writes to the board; iot sends a command through the IoT hub, which reaches the board over TLS in about 0.1 s. MCP every call USB serial iot TLS AI assistant Claude Code, Claude Desktop, Cursor, VS Code Gekko MCP server, on your computer 24 tools 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. Pins 1 to 12 run down the left side and pins 13 to 24 up the right. Device I/O is pins 1 to 10, Build and flash 11 to 16, Debug 17 and 18, Hardware checks 19 and 20, Live and control 21 to 23, and Setup is pin 24. The package is cut away over the die, which is drawn with one block per tool group, and every pin's lead is bonded to the die by a wire. 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. Pins 1 to 12 run down the left side and pins 13 to 24 up the right. Device I/O is pins 1 to 10, Build and flash 11 to 16, Debug 17 and 18, Hardware checks 19 and 20, Live and control 21 to 23, and Setup is pin 24. The package is cut away over the die, which is drawn with one block per tool group, and every pin's lead is bonded to the die by a wire. 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, cut away to show the die (one block per tool group). 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, with a probe on GPIO18 VCC to VIN, TRIG to GPIO25, ECHO to GPIO18, GND to GND. A probe on GPIO18 draws the pin's voltage as a trace against the ESP32's 3.6 V absolute maximum. As wired, ECHO puts 5 V on GPIO18, a 3.3 V pin that is not 5 V tolerant, and the trace rises over the absolute maximum. With the divider, R1 (1k) in series with ECHO and R2 (2k) from GPIO18 to ground, GPIO18 sees 5 V × 2k / (1k + 2k) = 3.33 V and the trace stays under it. CH1 GPIO18 5.00V 3.6 V absolute maximum U1 · HC-SR04 VCCTRIGECHOGND VINGPIO25GND ESP32 DevKit V1 esp32_devkit, 3.3 V logic GPIO18 5 V 5 V R1 1k R2 2k 3.33 V
Figure 4. U1 on an ESP32 DevKit V1, with a probe on GPIO18. As wired, ECHO drives GPIO18 at 5.00 V, over the ESP32’s 3.6 V absolute maximum (dashed). 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.

5Remote 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. Drawn as an oscilloscope capture with two traces. Trace 1, command sent by the assistant or the dashboard, goes high first. Trace 2, command arrives at the board over TLS, goes high about 0.1 s later. A dashed arrow, the trip over the internet, joins the two rising edges. Cursors a and b sit on the two edges, and the gap between them measures about 0.1 s. Not to scale. Command sent AI or dashboard Command arrives board, over TLS a b TLS 1 2 ≈ 0.1 s
Figure 5. 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
6Supported 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).

7Installation: 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.