CircuitPython MCP Server — Setup Guide

1. Install dependencies

cd circuitpython-mcp
pip install mcp pyserial
# or with uv (recommended):
uv pip install mcp pyserial

2. Test the server runs

python server.py
# Should hang silently — that means it's waiting for MCP input. Ctrl-C to stop.

3. Register with Claude Code (user scope — available in all projects)

claude mcp add --scope user circuitpython-repl -- python /ABSOLUTE/PATH/TO/circuitpython-mcp/server.py

Replace /ABSOLUTE/PATH/TO/ with the actual path, e.g.:

claude mcp add --scope user circuitpython-repl -- python ~/projects/circuitpython-mcp/server.py

4. Verify it's registered

claude mcp list

You should see circuitpython-repl in the list.

5. Inside Claude Code, check it connected

Type /mcp — you should see:

• circuitpython-repl: connected

---

Usage inside Claude Code

Just talk naturally:

• "List the available serial ports"
• "Connect to /dev/tty.usbmodem14201"
• "Run import board; print(dir(board)) on the board"
• "Execute this file on the board and show me any errors"
• "Soft reset the board"
• "The board seems stuck, interrupt it"

---

Troubleshooting

Permission denied on Linux:

sudo usermod -aG dialout $USER
# then log out and back in

Port not found: On macOS, CircuitPython boards usually appear as /dev/tty.usbmodem* On Linux: /dev/ttyACM0 or /dev/ttyUSB0 On Windows: COM3, COM4, etc.

Use list_ports tool to discover the right port.

Server shows "failed" in /mcp: Check the path is absolute and Python can import mcp and serial:

python -c "import mcp, serial; print('OK')"