Session 6 · Uploading to Arduino from Cursor
Uploading to Arduino from Cursor
This page shows how to ask in Cursor chat to write Arduino code, compile it, upload it to the board, and read the values the board sends to check that it runs correctly. Copy the setup text below and paste it into Cursor chat, and the agent does the installing and connecting. You type almost no commands yourself.
Three programs share the same folders.
| Program | What it does |
|---|---|
| Arduino IDE | The window for looking at code and uploading by hand. Use it to open and check sketches |
| Arduino CLI | The program that actually compiles and uploads inside the IDE |
| Arduino MCP | A server that lets Cursor's agent call the CLI as a tool (arduino-mcp-server) |
The IDE and the CLI are set to share the board files folder and the sketchbook (Documents/Arduino), so a sketch made in Cursor opens as is in the IDE, and board files installed through the IDE also work in Cursor.
What the agent can know
The agent cannot see the board. It can know three things.
| What to check | What the agent sees |
|---|---|
| Whether the code has syntax errors | The compile result |
| Whether it reached the board | The upload result |
| How the code runs on the board | The lines the code sends with Serial.println |
So make the code send its own state over serial, one line at a time. Print sensor values, motor angles and the current step like sensor=512 motor=90 state=RUN, and the agent reads those lines through MCP and compares them with what it expected. A person checks with their own eyes whether the motor actually turned, the LED lit up and the wiring is right.
Before you start
- Node.js 20 or later: In a terminal opened from the Cursor menu Terminal → New Terminal, type
node --version.v20or higher is fine. If it's lower or missing, install the LTS from nodejs.org. - Homebrew on Mac: If
brew --versiondoesn't work, paste the install command from the front page of brew.sh into the Mac Terminal app and run it. Enter your Mac password when asked (it is normal that nothing shows on screen). Also run the two lines underNext stepsat the end. - Put Cursor chat in Agent mode.
Paste the setup text
Click the Copy button at the top right of the text for your operating system, paste it into Cursor chat and send it. Each time the agent asks to run a command, click Run. It takes 10 to 20 minutes.
Mac
# Set up Cursor to write Arduino sketches directly (macOS)
Install Arduino IDE, Arduino CLI and Arduino MCP on macOS and connect them to Cursor. When done, I should be able to write and edit `.ino` files in `~/Documents/Arduino` from Cursor and compile them through MCP. Upload only after a board is connected.
## Install
- Install `arduino-cli` and the cask `arduino-ide` with Homebrew. Skip the IDE if `/Applications/Arduino IDE.app` already exists.
- Install `arduino-mcp-server` globally with npm. It needs Node 20 or later. If it fails with a permission error (EACCES), do not use sudo; run `npm config set prefix ~/.npm-global` and install again.
- Use absolute paths for executables. Check the real paths on this Mac with `brew --prefix`, `which arduino-cli`, `which arduino-mcp-server` and `which node`. On Apple Silicon Homebrew it is `/opt/homebrew/bin`. Cursor does not inherit the shell PATH.
## CLI and sketchbook
- Create the config with `arduino-cli config init`. If it already exists, do not overwrite it; only set the two values below.
- `directories.data` is `~/Library/Arduino15`
- `directories.user` is `~/Documents/Arduino`
- Make the IDE and the CLI share this data folder and sketchbook.
- Run `arduino-cli core update-index`, then install the `arduino:avr` core. This core compiles Uno, Nano, Mega and Leonardo right away.
- Install other cores such as ESP32 only when asked.
## Cursor MCP
Add a server named `arduino` to `~/.cursor/mcp.json`. Create the file if it doesn't exist, and leave any other MCP servers as they are.
```json
{
"mcpServers": {
"arduino": {
"command": "/opt/homebrew/bin/arduino-mcp-server",
"args": [],
"env": {
"ARDUINO_CLI_PATH": "/opt/homebrew/bin/arduino-cli",
"ARDUINO_SKETCH_ROOT": "/Users/USER/Documents/Arduino",
"PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
}
}
}
}
```
Replace `/Users/USER` and the Homebrew prefix with the real paths on this Mac. If the folder of `which node` is not in the PATH value, add it at the front. MCP does not handle sketches outside `ARDUINO_SKETCH_ROOT`. Create sketches as `SketchName/SketchName.ino`.
## Working rules
Create `~/Documents/Arduino/.cursor/rules/arduino.mdc` with the content below. Do not overwrite it if it already exists.
```markdown
---
description: Rules for working with the Arduino board
alwaysApply: true
---
- Compile, upload, find boards and read serial with the tools of the MCP server `arduino`.
- Find the board with `detect_hardware`. If unknown, assume an Arduino Uno (`arduino:avr:uno`).
- Create sketches inside this folder as `SketchName/SketchName.ino`.
- Upload only when the board appears in `list_connected_boards`. If it doesn't, stop after compiling and say so.
- Put `Serial.begin(9600)` in the code, and each time the state changes, print one line of `name=value` pairs separated by spaces, e.g. `sensor=512 motor=90 state=RUN`
- After uploading, read a few seconds with `read_serial_snapshot` and check that the expected values appear. If they differ, find the cause, fix it and upload again.
- Close any session opened with `serial_open_session` using `serial_close_session` when done. While it is open, nothing can be uploaded to that port.
- Serial cannot tell whether a motor or LED actually moved. Ask the person to check by eye.
- Write the pin numbers and wiring in a comment at the top of the code.
```
## Check
- `arduino-cli version` works.
- `arduino:avr` is in `arduino-cli core list`.
- Create `~/Documents/Arduino/Blink/Blink.ino` and compile it successfully for `arduino:avr:uno`.
- `arduino-mcp-server` starts over stdio, and `arduino_cli_doctor` returns the absolute path of the installed `arduino-cli`. This server's stdio is one-line JSON.
- Open that Blink sketch in the Arduino IDE.
Finish the install and compile checks even without a board. Check for a connection only with `arduino-cli board list`, and do not upload if there is none.
At the end, tell me briefly what I need to do (turn on MCP in Cursor, open the `~/Documents/Arduino` folder).
Windows
# Set up Cursor to write Arduino sketches directly (Windows)
Install Arduino IDE, Arduino CLI and Arduino MCP on Windows and connect them to Cursor. When done, I should be able to write and edit `.ino` files in the `Arduino` folder inside Documents from Cursor and compile them through MCP. Upload only after a board is connected. Run commands in PowerShell.
## Install
- Install Arduino CLI with `winget install --id ArduinoSA.CLI -e`. It installs to `C:\Program Files\Arduino CLI\arduino-cli.exe`. If an administrator prompt appears, wait until I click **Yes**.
- If the Arduino IDE is not installed, install it with `winget install --id ArduinoSA.IDE.stable -e`. Skip it if Arduino IDE is already in the Start menu.
- Install the MCP server with `npm install -g arduino-mcp-server`. It needs Node 20 or later.
- Use absolute paths for executables. Check the real paths on this computer with `where.exe node` and `npm root -g`. A terminal opened before the install does not know the new PATH, so write the paths out.
## CLI and sketchbook
- Check the real location of the Documents folder with `[Environment]::GetFolderPath('MyDocuments')`. It may have been moved to OneDrive. Below, `<Documents>` means this path.
- Create the config with `arduino-cli config init`. If it already exists, do not overwrite it; only set the two values below.
- `directories.data` is the real path of `%LOCALAPPDATA%\Arduino15`
- `directories.user` is `<Documents>\Arduino`
- Make the IDE and the CLI share this data folder and sketchbook.
- Run `arduino-cli core update-index`, then install the `arduino:avr` core. This core compiles Uno, Nano, Mega and Leonardo right away.
- Install other cores such as ESP32 only when asked.
## Cursor MCP
Add a server named `arduino` to `%USERPROFILE%\.cursor\mcp.json`. Create the file if it doesn't exist, and leave any other MCP servers as they are. Run the server file directly with node instead of the `.cmd` shim. Write paths in the JSON with `/`.
```json
{
"mcpServers": {
"arduino": {
"command": "C:/Program Files/nodejs/node.exe",
"args": ["C:/Users/USER/AppData/Roaming/npm/node_modules/arduino-mcp-server/build/index.js"],
"env": {
"ARDUINO_CLI_PATH": "C:/Program Files/Arduino CLI/arduino-cli.exe",
"ARDUINO_SKETCH_ROOT": "C:/Users/USER/Documents/Arduino"
}
}
}
}
```
Replace the `node.exe` path, the `npm root -g` path, `USER` and the Documents folder with the real paths on this computer. MCP does not handle sketches outside `ARDUINO_SKETCH_ROOT`. Create sketches as `SketchName/SketchName.ino`.
## Working rules
Create `<Documents>\Arduino\.cursor\rules\arduino.mdc` with the content below. Do not overwrite it if it already exists.
```markdown
---
description: Rules for working with the Arduino board
alwaysApply: true
---
- Compile, upload, find boards and read serial with the tools of the MCP server `arduino`.
- Find the board with `detect_hardware`. If unknown, assume an Arduino Uno (`arduino:avr:uno`).
- Create sketches inside this folder as `SketchName/SketchName.ino`.
- Upload only when the board appears in `list_connected_boards`. If it doesn't, stop after compiling and say so.
- Put `Serial.begin(9600)` in the code, and each time the state changes, print one line of `name=value` pairs separated by spaces, e.g. `sensor=512 motor=90 state=RUN`
- After uploading, read a few seconds with `read_serial_snapshot` and check that the expected values appear. If they differ, find the cause, fix it and upload again.
- Close any session opened with `serial_open_session` using `serial_close_session` when done. While it is open, nothing can be uploaded to that port.
- Serial cannot tell whether a motor or LED actually moved. Ask the person to check by eye.
- Write the pin numbers and wiring in a comment at the top of the code.
```
## Check
- `arduino-cli version` works (calling it by absolute path is fine).
- `arduino:avr` is in `arduino-cli core list`.
- Create `<Documents>\Arduino\Blink\Blink.ino` and compile it successfully for `arduino:avr:uno`.
- The server starts over stdio with the command and args written in mcp.json, and `arduino_cli_doctor` returns the absolute path of the installed `arduino-cli.exe`. This server's stdio is one-line JSON.
- Open that Blink sketch in the Arduino IDE.
Finish the install and compile checks even without a board. Check for a connection only with `arduino-cli board list`, and do not upload if there is none.
At the end, tell me briefly what I need to do (quit and reopen Cursor completely, turn on MCP, open the `Arduino` folder in Documents).
Turn on MCP in Cursor
- Quit Cursor completely and open it again.
- In Cursor Settings → MCP (or Tools & MCP), turn on the switch next to
arduino. A green light means it's connected. If it's red, see When you get stuck. - Open the
Documents/Arduinofolder with File → Open Folder. MCP only handles sketches inside this folder.
Check it works
Paste this into chat.
Use arduino_cli_doctor from the arduino MCP to check the install, then compile the Blink sketch for arduino:avr:uno.
If it reports something like Sketch uses ... bytes, you're ready. This works without a board.
Try it
Plug the board in over USB and write in chat:
Make a sketch that blinks LED_BUILTIN every 0.5 seconds.
Each time it turns on or off, print led=1 or led=0 and the blink count so far over serial.
Compile it, find the connected board and upload, then read serial for 5 seconds and check that it runs correctly.
Each time the agent asks to use an MCP tool, read it and click Run. It worked if the agent shows the lines it received and gives its verdict. Check by eye that the LED on the board is blinking.
If you attached a sensor, ask like this:
Print the value of the sensor on A0 every 0.2 seconds as sensor=value.
While you read for 15 seconds after uploading, I'll touch the sensor. Tell me when and how much the value changed.
Open the same sketch in the Arduino IDE with File → Open and you'll see the code edited in Cursor. Upload from only one side at a time. If the IDE serial monitor is open, MCP cannot use the port.
When you get stuck
- MCP shows a red light: Ask in chat "The arduino server in
~/.cursor/mcp.jsonwon't start. Check that the command and args paths really exist and fix them", then reopen Cursor. - Upload fails / the port is busy: Only one program can use a port at a time. Close the Arduino IDE serial monitor and tell the agent "Close all open serial sessions and upload again".
- The board doesn't show up: See the last section of Installing the Arduino IDE for charge-only cables and drivers for compatible boards.
- No lines arrive at all: Have the agent check that the
Serial.begin(...)value matches the read speed, and that the code hasSerial.println. - An error saying the path is outside
ARDUINO_SKETCH_ROOT: Check that the folder open in Cursor isDocuments/Arduino.
Without MCP, from the terminal
You can also skip the MCP server and have the agent call arduino-cli directly in the terminal. Serial is read with a small script that reads for a set time and then stops.
Install arduino-cli
Open Cursor and open the terminal with Ctrl/⌘+`.
Windows
winget install ArduinoSA.CLI
When it finishes, quit Cursor completely and open it again. A new terminal needs that to find arduino-cli.
Mac
If you have Homebrew:
brew install arduino-cli
If you don't have Homebrew, first make the work folder (see "Make a work folder" below) and run this in that folder. It installs into bin/ inside the folder.
curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | sh
Both: get the board files
arduino-cli core update-index
arduino-cli core install arduino:avr
You're done when you see Platform arduino:avr@... installed. If you already got it through the Arduino IDE, you'll see already installed. If you installed into bin/ on Mac, put ./bin/ in front of arduino-cli.
Make a work folder
Make a new folder (for example arduino-lab) and open it in Cursor with File → Open Folder. In the terminal, get the package used to read serial. This uses the Node.js you installed in Session 1.
npm install serialport
Create a file called serial-read.mjs at the top of the folder and paste the following. The script reads the lines the board sends for a set time and then stops. arduino-cli monitor keeps running until you stop it yourself, so the agent never gets the result.
// Reads Arduino serial output for a set time, then exits.
// Usage: node serial-read.mjs <port> [baud=9600] [seconds=10]
// List ports: node serial-read.mjs --list
import { SerialPort, ReadlineParser } from "serialport";
const [port, baud = "9600", secs = "10"] = process.argv.slice(2);
if (!port || port === "--list") {
const ports = await SerialPort.list();
for (const p of ports) console.log(p.path, p.manufacturer ?? "");
if (!ports.length) console.log("No ports connected.");
process.exit(0);
}
const sp = new SerialPort({ path: port, baudRate: Number(baud) }, (err) => {
if (err) {
console.error(`Cannot open port: ${err.message}`);
console.error("Check that no other program (such as the Arduino IDE serial monitor) is using the port.");
process.exit(1);
}
console.error(`[${port} @ ${baud}] Reading for ${secs} seconds.`);
});
const start = Date.now();
let lines = 0;
sp.pipe(new ReadlineParser({ delimiter: "\n" })).on("data", (line) => {
lines++;
const t = ((Date.now() - start) / 1000).toFixed(1).padStart(5);
console.log(`${t}s ${line.replace(/\r$/, "")}`);
});
setTimeout(() => {
console.error(`[done] ${lines} lines received.${lines ? "" : " Nothing arrived. Check the baud rate (the Serial.begin value) and the port."}`);
sp.close(() => process.exit(0));
}, Number(secs) * 1000);
Give the agent rules
Create the file .cursor/rules/arduino.mdc in the folder and paste the following. The agent reads and follows these rules in every conversation.
---
description: Rules for working with the Arduino board
alwaysApply: true
---
- The board is an Arduino Uno (`arduino:avr:uno`). For another board, check the FQBN with `arduino-cli board list` and change it.
- If `arduino-cli` is not found, use `./bin/arduino-cli`.
- Keep each sketch as an .ino file with the same name as its folder, e.g. `blink/blink.ino`
- Compile: `arduino-cli compile --fqbn arduino:avr:uno <sketch folder>`
- Find the port: `arduino-cli board list`
- Upload: `arduino-cli upload -p <port> --fqbn arduino:avr:uno <sketch folder>`
- Read serial: `node serial-read.mjs <port> 9600 10`. Do not use `arduino-cli monitor`, because it never ends.
- Put `Serial.begin(9600)` in the code, and each time the state changes, print one line of `name=value` pairs separated by spaces, e.g. `sensor=512 motor=90 state=RUN`
- After uploading, read serial and check that the expected values appear. If they differ, find the cause, fix it and upload again.
- Serial cannot tell whether a motor or LED actually moved. Ask the person to check by eye.
- Write the pin numbers and wiring in a comment at the top of the code.
Then ask in chat something like "Make a blink sketch, compile it, upload it to the connected board, and read serial for 10 seconds to check it".