# Cursor에서 아두이노 올리기

Cursor 채팅에 말로 시켜서 아두이노 코드를 쓰고, 컴파일하고, 보드에 올리고, 보드가 보내는 값을 읽어 제대로 도는지까지 확인하는 방법입니다. 아래 설정 글을 복사해 Cursor 채팅에 붙여 넣으면 에이전트가 설치와 연결을 합니다. 직접 칠 명령은 거의 없습니다.

세 프로그램이 같은 폴더를 같이 씁니다.

| 프로그램 | 하는 일 |
| --- | --- |
| **Arduino IDE** | 코드를 눈으로 보고 직접 올릴 때 쓰는 창. 스케치를 열어 확인할 때 씁니다 |
| **Arduino CLI** | IDE 안에서 실제로 컴파일하고 업로드하는 프로그램 |
| **Arduino MCP** | Cursor의 에이전트가 CLI를 도구로 부르게 이어 주는 서버([arduino-mcp-server](https://www.npmjs.com/package/arduino-mcp-server)) |

IDE와 CLI가 보드 파일 폴더와 스케치북(`문서/Arduino`)을 함께 쓰도록 맞춰서, Cursor에서 만든 스케치를 IDE에서 그대로 열 수 있고 IDE에서 받은 보드 파일을 Cursor에서도 씁니다.

## 에이전트가 알 수 있는 것

에이전트는 보드를 볼 수 없습니다. 알 수 있는 것은 세 가지입니다.

| 확인할 것 | 에이전트가 보는 것 |
| --- | --- |
| 코드에 문법 오류가 없는지 | 컴파일 결과 |
| 보드에 잘 올라갔는지 | 업로드 결과 |
| 보드에서 코드가 어떻게 도는지 | 코드가 `Serial.println` 으로 보낸 줄 |

그래서 **코드가 자기 상태를 시리얼로 한 줄씩 보내게** 만듭니다. 센서 값, 모터 각도, 지금 어느 단계인지를 `sensor=512 motor=90 state=RUN` 처럼 찍으면 에이전트가 MCP로 그 줄을 읽고 기대한 값과 비교합니다. 모터가 실제로 돌았는지, LED가 켜졌는지, 배선이 맞는지는 사람이 눈으로 봅니다.

## 준비

- **Node.js 20 이상**: Cursor 메뉴 **Terminal → New Terminal** 로 연 터미널에서 `node --version` 을 쳐서 `v20` 이상이면 됩니다. 낮거나 없으면 [nodejs.org](https://nodejs.org) 에서 **LTS** 를 설치합니다.
- **Mac은 Homebrew**: 터미널에서 `brew --version` 이 안 되면 [brew.sh](https://brew.sh) 첫 화면의 설치 명령을 Mac의 **터미널** 앱에 붙여 넣고 실행합니다. 맥 비밀번호를 물으면 입력합니다(화면에 보이지 않는 것이 정상). 끝에 나오는 `Next steps` 의 두 줄도 그대로 실행합니다.
- Cursor 채팅을 **Agent** 모드로 둡니다.

## 설정 글 붙여 넣기

내 운영체제의 글 오른쪽 위 **복사** 단추를 누르고, Cursor 채팅에 붙여 넣어 보냅니다. 에이전트가 명령을 실행하겠다고 물을 때마다 **Run** 을 누릅니다. 10~20분 걸립니다.

### Mac

````text
# Cursor에서 아두이노 스케치를 바로 작성하게 설정 (macOS)

macOS에 Arduino IDE, Arduino CLI, Arduino MCP를 설치하고 Cursor에 연결해 주세요. 끝나면 Cursor에서 `~/Documents/Arduino` 안의 `.ino`를 작성·수정하고, MCP로 컴파일할 수 있어야 합니다. 업로드는 보드가 연결된 뒤에만 하면 됩니다.

## 설치

- Homebrew로 `arduino-cli`와 cask `arduino-ide`를 설치한다. `/Applications/Arduino IDE.app`이 이미 있으면 IDE는 건너뛴다.
- npm 전역으로 `arduino-mcp-server`를 설치한다. Node 20 이상이어야 한다. 권한 오류(EACCES)가 나면 sudo를 쓰지 말고 `npm config set prefix ~/.npm-global`로 바꾼 뒤 다시 설치한다.
- 실행 파일은 절대 경로로 쓴다. `brew --prefix`, `which arduino-cli`, `which arduino-mcp-server`, `which node`로 이 맥의 실제 경로를 확인한다. Apple Silicon Homebrew 기준으로는 `/opt/homebrew/bin`이다. Cursor는 셸 PATH를 물려받지 않는다.

## CLI와 스케치북

- `arduino-cli config init`으로 설정을 만든다. 이미 있으면 기존 파일을 덮어쓰지 말고 아래 두 값만 맞춘다.
- `directories.data`는 `~/Library/Arduino15`
- `directories.user`는 `~/Documents/Arduino`
- IDE와 CLI가 이 데이터 폴더와 스케치북을 같이 쓰게 한다.
- `arduino-cli core update-index` 후 `arduino:avr` 코어를 설치한다. Uno, Nano, Mega, Leonardo를 바로 컴파일하기 위한 코어다.
- ESP32 등 다른 코어는 요청이 있을 때만 설치한다.

## Cursor MCP

`~/.cursor/mcp.json`에 서버 이름 `arduino`를 추가한다. 파일이 없으면 만들고, 이미 있는 다른 MCP 서버는 그대로 둔다.

```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"
      }
    }
  }
}
```

`/Users/USER`와 Homebrew prefix는 이 맥의 실제 경로로 바꾼다. `which node`가 있는 폴더가 PATH 값에 없으면 앞에 더한다. `ARDUINO_SKETCH_ROOT` 밖의 스케치는 MCP가 다루지 않는다. 스케치는 `스케치이름/스케치이름.ino` 형태로 만든다.

## 작업 규칙

`~/Documents/Arduino/.cursor/rules/arduino.mdc`를 아래 내용으로 만든다. 이미 있으면 덮어쓰지 않는다.

```markdown
---
description: 아두이노 보드 작업 규칙
alwaysApply: true
---

- 컴파일, 업로드, 보드 찾기, 시리얼 읽기는 MCP 서버 `arduino` 의 도구로 한다.
- 보드는 `detect_hardware` 로 찾는다. 모르면 Arduino Uno(`arduino:avr:uno`)로 본다.
- 스케치는 이 폴더 안에 `스케치이름/스케치이름.ino` 로 만든다.
- 업로드는 `list_connected_boards` 에 보드가 보일 때만 한다. 없으면 컴파일까지만 하고 알려 준다.
- 코드에는 `Serial.begin(9600)` 을 넣고, 상태가 바뀔 때마다 `이름=값` 을 공백으로 이어 한 줄로 찍는다. 예: `sensor=512 motor=90 state=RUN`
- 업로드한 뒤에는 `read_serial_snapshot` 으로 몇 초 읽어 기대한 값이 나오는지 확인한다. 다르면 원인을 찾아 고치고 다시 올린다.
- `serial_open_session` 으로 연 세션은 끝나면 `serial_close_session` 으로 닫는다. 열려 있으면 그 포트로 업로드할 수 없다.
- 모터나 LED가 실제로 움직였는지는 시리얼로 알 수 없다. 사람에게 눈으로 확인해 달라고 묻는다.
- 핀 번호와 배선은 코드 맨 위 주석에 적는다.
```

## 확인

- `arduino-cli version`이 동작한다.
- `arduino:avr`이 `arduino-cli core list`에 있다.
- `~/Documents/Arduino/Blink/Blink.ino`를 만들고 `arduino:avr:uno`로 컴파일해 성공한다.
- `arduino-mcp-server`가 stdio로 기동하고, `arduino_cli_doctor`가 설치한 `arduino-cli` 절대 경로를 반환한다. 이 서버의 stdio는 한 줄짜리 JSON이다.
- Arduino IDE로 그 Blink 스케치를 연다.

보드가 없어도 설치와 컴파일 확인은 끝낸다. 연결은 `arduino-cli board list`로만 보고, 없으면 업로드하지 않는다.
마지막에 내가 할 일(Cursor에서 MCP 켜기, `~/Documents/Arduino` 폴더 열기)을 짧게 알려 준다.
````

### Windows

````text
# Cursor에서 아두이노 스케치를 바로 작성하게 설정 (Windows)

Windows에 Arduino IDE, Arduino CLI, Arduino MCP를 설치하고 Cursor에 연결해 주세요. 끝나면 Cursor에서 문서 폴더의 `Arduino` 안 `.ino`를 작성·수정하고, MCP로 컴파일할 수 있어야 합니다. 업로드는 보드가 연결된 뒤에만 하면 됩니다. 명령은 PowerShell로 실행한다.

## 설치

- `winget install --id ArduinoSA.CLI -e`로 Arduino CLI를 설치한다. `C:\Program Files\Arduino CLI\arduino-cli.exe`에 설치된다. 관리자 권한 창이 뜨면 내가 **예**를 누를 때까지 기다린다.
- Arduino IDE가 없으면 `winget install --id ArduinoSA.IDE.stable -e`로 설치한다. 시작 메뉴에 Arduino IDE가 이미 있으면 건너뛴다.
- `npm install -g arduino-mcp-server`로 MCP 서버를 설치한다. Node 20 이상이어야 한다.
- 실행 파일은 절대 경로로 쓴다. `where.exe node`, `npm root -g`로 이 컴퓨터의 실제 경로를 확인한다. 설치 직후의 터미널은 새 PATH를 모르므로 경로를 직접 적는다.

## CLI와 스케치북

- 문서 폴더의 실제 위치를 `[Environment]::GetFolderPath('MyDocuments')`로 확인한다. OneDrive로 옮겨져 있을 수 있다. 아래에서 `<문서>`는 이 경로다.
- `arduino-cli config init`으로 설정을 만든다. 이미 있으면 기존 파일을 덮어쓰지 말고 아래 두 값만 맞춘다.
- `directories.data`는 `%LOCALAPPDATA%\Arduino15`의 실제 경로
- `directories.user`는 `<문서>\Arduino`
- IDE와 CLI가 이 데이터 폴더와 스케치북을 같이 쓰게 한다.
- `arduino-cli core update-index` 후 `arduino:avr` 코어를 설치한다. Uno, Nano, Mega, Leonardo를 바로 컴파일하기 위한 코어다.
- ESP32 등 다른 코어는 요청이 있을 때만 설치한다.

## Cursor MCP

`%USERPROFILE%\.cursor\mcp.json`에 서버 이름 `arduino`를 추가한다. 파일이 없으면 만들고, 이미 있는 다른 MCP 서버는 그대로 둔다. `.cmd` 대신 node로 서버 파일을 직접 실행한다. JSON 안 경로는 `/`로 쓴다.

```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"
      }
    }
  }
}
```

`node.exe` 경로, `npm root -g` 경로, `USER`, 문서 폴더는 이 컴퓨터의 실제 경로로 바꾼다. `ARDUINO_SKETCH_ROOT` 밖의 스케치는 MCP가 다루지 않는다. 스케치는 `스케치이름/스케치이름.ino` 형태로 만든다.

## 작업 규칙

`<문서>\Arduino\.cursor\rules\arduino.mdc`를 아래 내용으로 만든다. 이미 있으면 덮어쓰지 않는다.

```markdown
---
description: 아두이노 보드 작업 규칙
alwaysApply: true
---

- 컴파일, 업로드, 보드 찾기, 시리얼 읽기는 MCP 서버 `arduino` 의 도구로 한다.
- 보드는 `detect_hardware` 로 찾는다. 모르면 Arduino Uno(`arduino:avr:uno`)로 본다.
- 스케치는 이 폴더 안에 `스케치이름/스케치이름.ino` 로 만든다.
- 업로드는 `list_connected_boards` 에 보드가 보일 때만 한다. 없으면 컴파일까지만 하고 알려 준다.
- 코드에는 `Serial.begin(9600)` 을 넣고, 상태가 바뀔 때마다 `이름=값` 을 공백으로 이어 한 줄로 찍는다. 예: `sensor=512 motor=90 state=RUN`
- 업로드한 뒤에는 `read_serial_snapshot` 으로 몇 초 읽어 기대한 값이 나오는지 확인한다. 다르면 원인을 찾아 고치고 다시 올린다.
- `serial_open_session` 으로 연 세션은 끝나면 `serial_close_session` 으로 닫는다. 열려 있으면 그 포트로 업로드할 수 없다.
- 모터나 LED가 실제로 움직였는지는 시리얼로 알 수 없다. 사람에게 눈으로 확인해 달라고 묻는다.
- 핀 번호와 배선은 코드 맨 위 주석에 적는다.
```

## 확인

- `arduino-cli version`이 동작한다(절대 경로로 불러도 된다).
- `arduino:avr`이 `arduino-cli core list`에 있다.
- `<문서>\Arduino\Blink\Blink.ino`를 만들고 `arduino:avr:uno`로 컴파일해 성공한다.
- mcp.json에 적은 command와 args로 서버가 stdio로 기동하고, `arduino_cli_doctor`가 설치한 `arduino-cli.exe` 절대 경로를 반환한다. 이 서버의 stdio는 한 줄짜리 JSON이다.
- Arduino IDE로 그 Blink 스케치를 연다.

보드가 없어도 설치와 컴파일 확인은 끝낸다. 연결은 `arduino-cli board list`로만 보고, 없으면 업로드하지 않는다.
마지막에 내가 할 일(Cursor 완전히 다시 열기, MCP 켜기, 문서의 `Arduino` 폴더 열기)을 짧게 알려 준다.
````

## Cursor에서 MCP 켜기

1. Cursor를 완전히 닫았다가 다시 엽니다.
2. **Cursor Settings → MCP** (또는 **Tools & MCP**)에서 `arduino` 옆 스위치를 켭니다. 초록 불이 들어오면 연결된 것입니다. 빨간 불이면 [막힐 때](#막힐-때)를 봅니다.
3. **File → Open Folder** 로 `문서/Arduino` 폴더를 엽니다. MCP는 이 폴더 안의 스케치만 다룹니다.

## 확인하기

채팅에 붙여 넣습니다.

```text
arduino MCP 의 arduino_cli_doctor 로 설치 상태를 보고, Blink 스케치를 arduino:avr:uno 로 컴파일해 줘.
```

`Sketch uses ... bytes` 와 비슷한 결과를 알려 주면 준비가 끝났습니다. 보드 없이도 여기까지 됩니다.

## 시켜 보기

보드를 USB로 꽂고 채팅에 씁니다.

```text
LED_BUILTIN 을 0.5초 간격으로 깜빡이는 스케치를 만들어 줘.
켜고 끌 때마다 led=1, led=0 과 지금까지 깜빡인 횟수를 시리얼로 찍어 줘.
컴파일하고, 연결된 보드를 찾아 업로드한 뒤, 5초 동안 시리얼을 읽어서 제대로 도는지 확인해 줘.
```

에이전트가 MCP 도구를 쓰겠다고 물을 때마다 내용을 보고 **Run**. 받은 줄을 보여 주고 판단을 말하면 성공입니다. 보드 위 LED가 깜빡이는지는 눈으로 확인합니다.

센서를 붙였다면 이렇게 시킵니다.

```text
A0 에 연결한 센서 값을 0.2초마다 sensor=값 으로 찍게 해 줘.
올리고 15초 읽는 동안 내가 센서에 손을 댈게. 값이 언제 얼마나 바뀌었는지 알려 줘.
```

같은 스케치를 Arduino IDE에서 **File → Open** 으로 열면 Cursor에서 고친 코드가 그대로 보입니다. 업로드는 한쪽에서만 합니다. IDE의 시리얼 모니터가 열려 있으면 MCP가 포트를 쓰지 못합니다.

> [!TIP]
> 시리얼 포트를 열면 Uno는 대부분 처음부터 다시 시작합니다. 읽기 첫 1~2초에 `setup()` 에서 찍은 줄이 다시 보이는 것은 정상입니다.

## 막힐 때

- **MCP가 빨간 불이다**: 채팅에 「`~/.cursor/mcp.json` 의 arduino 서버가 안 켜진다. command 와 args 경로가 실제로 있는지 확인하고 고쳐 줘」라고 시킨 뒤 Cursor를 다시 엽니다.
- **업로드가 안 된다 / 포트가 바쁘다**: 포트는 한 번에 한 프로그램만 씁니다. Arduino IDE의 시리얼 모니터를 닫고, 에이전트에게 「열린 시리얼 세션을 모두 닫고 다시 올려 줘」라고 합니다.
- **보드가 안 보인다**: 충전 전용 케이블인지, 호환 보드 드라이버가 필요한지 [Arduino IDE 설치](https://opencircuit.club/wiki/lab/arduino) 글의 마지막 절을 봅니다.
- **줄이 하나도 안 온다**: 코드의 `Serial.begin(...)` 값과 읽는 속도가 같은지, 코드에 `Serial.println` 이 있는지 에이전트에게 확인시킵니다.
- **`ARDUINO_SKETCH_ROOT` 밖이라는 오류**: Cursor에서 연 폴더가 `문서/Arduino` 인지 봅니다.

## MCP 없이 터미널로 하기

MCP 서버를 쓰지 않고, 에이전트가 터미널에서 arduino-cli를 직접 부르게 할 수도 있습니다. 시리얼은 정해진 시간만 읽고 끝나는 작은 스크립트로 읽습니다.

### arduino-cli 설치

Cursor를 열고 <kbd>Ctrl/⌘</kbd>+<kbd>`</kbd> 로 터미널을 엽니다.

#### Windows

```powershell
winget install ArduinoSA.CLI
```

끝나면 **Cursor를 완전히 닫았다가 다시 엽니다.** 그래야 새 터미널이 `arduino-cli` 를 찾습니다.

> [!NOTE]
> `winget` 이 없다고 나오면 [GitHub 릴리스](https://github.com/arduino/arduino-cli/releases/latest)에서 `Windows_64bit.msi` 를 받아 설치하고 Cursor를 다시 엽니다.

#### Mac

Homebrew가 있으면:

```bash
brew install arduino-cli
```

Homebrew가 없으면 작업할 폴더(아래 「작업 폴더 만들기」)를 먼저 만들고, 그 폴더에서 실행합니다. 폴더 안 `bin/` 에 설치됩니다.

```bash
curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | sh
```

#### 공통: 보드 파일 받기

```bash
arduino-cli core update-index
arduino-cli core install arduino:avr
```

`Platform arduino:avr@... installed` 가 나오면 됩니다. Arduino IDE에서 이미 받았다면 `already installed` 가 나옵니다. Mac에서 `bin/` 에 설치했다면 `arduino-cli` 앞에 `./bin/` 을 붙입니다.

### 작업 폴더 만들기

새 폴더(예: `arduino-lab`)를 만들고 Cursor에서 **File → Open Folder** 로 엽니다. 터미널에서 시리얼 읽기에 쓸 패키지를 받습니다. 1회차에 설치한 Node.js를 씁니다.

```bash
npm install serialport
```

폴더 맨 위에 `serial-read.mjs` 파일을 만들고 아래를 붙여 넣습니다. 보드가 보내는 줄을 정해진 시간만 읽고 끝나는 스크립트입니다. `arduino-cli monitor` 는 직접 끄기 전까지 계속 돌아서 에이전트가 결과를 받지 못합니다.

```js
// 아두이노 시리얼 출력을 정해진 시간만 읽고 끝냅니다.
// 사용: node serial-read.mjs <포트> [속도=9600] [초=10]
// 포트 목록: 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("연결된 포트가 없습니다.");
  process.exit(0);
}

const sp = new SerialPort({ path: port, baudRate: Number(baud) }, (err) => {
  if (err) {
    console.error(`포트를 열 수 없습니다: ${err.message}`);
    console.error("다른 프로그램(Arduino IDE 시리얼 모니터 등)이 포트를 쓰고 있지 않은지 확인하세요.");
    process.exit(1);
  }
  console.error(`[${port} @ ${baud}] ${secs}초 동안 읽습니다.`);
});

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(`[끝] ${lines}줄 받음.${lines ? "" : " 아무것도 오지 않았습니다. 속도(Serial.begin 값)와 포트를 확인하세요."}`);
  sp.close(() => process.exit(0));
}, Number(secs) * 1000);
```

### 에이전트에게 규칙 주기

폴더 안에 `.cursor/rules/arduino.mdc` 파일을 만들고 아래를 붙여 넣습니다. 에이전트가 대화마다 이 규칙을 읽고 따릅니다.

```markdown
---
description: 아두이노 보드 작업 규칙
alwaysApply: true
---

- 보드는 Arduino Uno(`arduino:avr:uno`)다. 다른 보드면 `arduino-cli board list` 로 FQBN을 확인해 바꾼다.
- `arduino-cli` 를 찾을 수 없으면 `./bin/arduino-cli` 를 쓴다.
- 스케치는 폴더 이름과 같은 이름의 .ino 로 둔다. 예: `blink/blink.ino`
- 컴파일: `arduino-cli compile --fqbn arduino:avr:uno <스케치 폴더>`
- 포트 찾기: `arduino-cli board list`
- 업로드: `arduino-cli upload -p <포트> --fqbn arduino:avr:uno <스케치 폴더>`
- 시리얼 읽기: `node serial-read.mjs <포트> 9600 10`. `arduino-cli monitor` 는 끝나지 않으니 쓰지 않는다.
- 코드에는 `Serial.begin(9600)` 을 넣고, 상태가 바뀔 때마다 `이름=값` 을 공백으로 이어 한 줄로 찍는다. 예: `sensor=512 motor=90 state=RUN`
- 업로드한 뒤에는 시리얼을 읽어 기대한 값이 나오는지 확인한다. 다르면 원인을 찾아 고치고 다시 올린다.
- 모터·LED가 실제로 움직였는지는 시리얼로 알 수 없다. 사람에게 눈으로 확인해 달라고 묻는다.
- 핀 번호와 배선은 코드 맨 위 주석에 적는다.
```

그다음 채팅에 「blink 스케치를 만들어 컴파일하고, 연결된 보드에 올린 뒤 10초 동안 시리얼을 읽어 확인해 줘」처럼 시킵니다.
