thonny-ai

The MCP server and AI plugin for Thonny. Let Claude Code, Claude Desktop, Cursor or any MCP client program your Raspberry Pi Pico and ESP32 in MicroPython, visibly, safely and hands-free.

Recorded with Thonny's local Python interpreter; with a board connected, the same tools drive MicroPython on the board.

thonny-ai connects AI coding assistants to Thonny, the beginner-friendly Python IDE used in many classrooms, and to the MicroPython board plugged into it. The AI can run code on the board, read sensors, watch a robot's main loop, manage files and deploy a project. Every command appears in Thonny's shell, in front of you, and you can require a click to approve each action.

• 🧑‍🏫 For students and teachers: the AI's work is visible and reviewable, not hidden in a chat.

• 🤖 For makers: “deploy, run, watch the sensor output, fix, repeat” without copy-paste.

• 🔌 For MCP users: a clean, dependency-free MCP server for real hardware.

Contents

Quick start · What you can ask · Features · Tools · Compatibility · How it works · Security · FAQ · Contributing

Related MCP server: pico-bay

Quick start

Option A: ready-made Thonny (Windows). Download Thonny-AI-portable.zip, unzip, run thonny.exe. Nothing to install.

Option B: your existing Thonny. In Thonny, open Tools → Open system shell… and run:

pip install git+https://github.com/AstroQuestStudio/thonny-ai

Then restart Thonny, open View → AI Assistant and click Connect Claude Code. Done: start a new Claude Code session (or type /mcp) and talk to your board.

The server is started with Thonny's own Python (python -m thonny_ai_mcp):

{
  "mcpServers": {
    "thonny-ai": {
      "command": "C:/path/to/Thonny/python.exe",
      "args": ["-m", "thonny_ai_mcp"],
      "env": { "THONNY_AI_PROJECT": "C:/path/to/your/project" }
    }
  }
}

• Claude Desktop: claude_desktop_config.json

• Cursor: .cursor/mcp.json

• Claude Code (manual): claude mcp add thonny-ai -s user -- "C:/path/to/Thonny/python.exe" -m thonny_ai_mcp

• Any other client that speaks MCP over stdio works the same way.

On macOS / Linux use the python3 Thonny runs with (Tools → Open system shell…, then which python3).

What you can ask

“Blink the Pico W's onboard LED 5 times.”

“Read the internal temperature sensor every second for 10 seconds and tell me if it drifts.”

“Start src/main.py and watch the ultrasonic distance readings. Are they noisy? Suggest a filter.”

“Deploy src/ to the board and check that main.py starts without errors.”

“What files are on the board, and how much flash is left?”

“My motor doesn't turn: check the PWM on GP15, then try duty 50%.”

Features

MCP tools

Compatibility

How it works

flowchart LR
    AI["AI client<br/>(Claude Code, Cursor…)"] -- "MCP / stdio" --> MCP["thonny_ai_mcp<br/>MCP server"]
    MCP -- "Thonny open:<br/>HTTP 127.0.0.1:47821" --> P["thonny-ai plugin<br/>inside Thonny"]
    P --> T["Thonny<br/>shell · panel · approval"]
    T -- USB --> B[("MicroPython board")]
    MCP -. "Thonny closed:<br/>serial raw REPL" .-> B

• A serial port can only be opened by one program. While Thonny is connected it owns the port, so the MCP server goes through Thonny. That is also why everything shows up in its shell.

• File transfers use Thonny's own backend commands, so they don't clutter the shell.

• Each MCP tool call is one operation: one approval and one row in the panel, even when it needs many round-trips (a sync of 20 files, for example).

Security model

• The bridge listens on 127.0.0.1 only.

• Every request must carry the X-Thonny-AI: 1 header, and requests with an Origin header are rejected, so web pages open in your browser cannot reach it.

• With Approve every AI action on, code execution and file changes wait for your click, and are denied after 2 minutes without an answer. Read-only actions (status, info, ls, read, monitor, shell) never wait.

• When you deny an action, the AI receives an explicit “denied by the user” error.

Found a problem? Please report it privately, see SECURITY.md.

FAQ

Yes: thonny-ai. It ships a Thonny plugin and an MCP server (python -m thonny_ai_mcp) that lets any MCP client drive Thonny and the MicroPython board connected to it.

Yes. With thonny-ai, Claude Code can run MicroPython on the board (exec), deploy a project (sync), start a long-running program and read its output live (start + monitor), and manage files, while you watch everything in Thonny.

No. Its code is echoed in Thonny's shell and every action is logged in the AI Assistant panel. Turn on Approve every AI action to allow or deny each action before it runs.

No. When Thonny is closed, the MCP server connects to the board over USB serial by itself. Keeping Thonny open gives you the visual log, the approval gate and auto-reconnect.

mpremote and rshell are command-line tools for humans and scripts. thonny-ai is built for AI agents working next to a human: MCP tools with structured results, long-running program monitoring, and visibility and approval inside the IDE students already use. They work well side by side.

Any client that supports MCP over stdio: Claude Code, Claude Desktop, Cursor, VS Code with MCP, and more. The model itself runs in your client. thonny-ai only runs locally.

That is what it was designed for: everything the AI does is visible in the shell, logged in a panel, and can require the student's (or teacher's) approval. It is MIT-licensed and free.

Why not just copy-paste into a chatbot?

Configuration

Development

python -m pip install -e ".[test]"
PYTHONPATH=tests python -m unittest discover -s tests -v   # 54 tests, no board needed
python tests/e2e_thonny.py /path/to/thonny.exe             # 21 steps in a real Thonny window
python bundle/build_portable.py thonny-X.Y.Z-windows-portable.zip

The unit tests use a fake board (sandboxed filesystem) and a fake serial port speaking the MicroPython raw REPL protocol. The end-to-end script drives a real Thonny through the MCP tools. Real-board behaviour is checked with the hardware checklist.

Contributing

Contributions are very welcome, from a translation to a new tool: see CONTRIBUTING.md and the good first issues. Hardware reports for boards other than the Pico W are especially useful.

Roadmap

• PyPI release and listing in Thonny's plugin manager

• Wi-Fi (WebREPL): drive robots that can't stay on a USB cable

• Plotter and variable snapshots for the AI

• More UI languages

Français

thonny-ai permet à un assistant IA (Claude Code ou tout client MCP) de piloter Thonny et ta carte MicroPython (Raspberry Pi Pico, ESP32). Le code de l'IA s'affiche dans la console Thonny comme s'il était tapé, chaque action peut être soumise à ta validation, l'IA peut lancer un programme qui tourne en boucle (un robot) et lire ce qu'il affiche en direct, et Thonny se reconnecte tout seul quand on rebranche la carte. L'interface est en français si Thonny est en français.

If thonny-ai saves you time, a ⭐ helps other students and makers find it.

MIT © Mathis Cottereau · Not affiliated with the Thonny project: thonny-ai is a third-party plugin built on Thonny's public plugin interface.