Connect via Serial (USB)

USB Serial is the simplest way to connect your MCU to MCP/U. It works with any Arduino-compatible board and requires no network configuration.

---

Finding Your Serial Port

1. Connect your board via USB

2. Find the port using the commands below for your operating system:

Linux

ls /dev/ttyUSB* /dev/ttyACM*

Typical output: /dev/ttyUSB0 or /dev/ttyACM0

macOS

ls /dev/tty.usbserial-* /dev/ttyUSB*

Typical output: /dev/cu.usbserial-1420 or /dev/cu.usbserial-*

Windows

Open Device Manager → Ports (COM & LPT)

Typical output: COM3, COM4, etc.

Tip

If you see multiple ports and aren’t sure which one is your board, unplug it, run the command again, then plug it back in and note which port appears.

---

Linux: Fix Permission Issues

On Linux, you may get a “Permission denied” error when accessing the serial port. This is because only members of the dialout group can access serial devices.

1. Add your user to the dialout group

   sudo usermod -aG dialout $USER

2. Log out and log back in (or reboot)

3. Verify membership

   groups | grep dialout

Caution

You must log out and back in for the group change to take effect. Simply opening a new terminal won’t work.

---

Configuring the Agent

Once you know your serial port, configure your AI agent:

Claude Desktop

{
  "mcpServers": {
    "mcpu": {
      "command": "npx",
      "args": ["mcpu-client"],
      "env": {
        "SERIAL_PORT": "/dev/ttyACM0"
      }
    }
  }
}

Config file location:

• Linux: ~/.config/claude/claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Claude Code

claude mcp add mcpu -e SERIAL_PORT=/dev/ttyACM0 -- npx mcpu-client

Gemini CLI

Edit ~/.gemini/settings.json:

{
  "mcpServers": {
    "mcpu": {
      "command": "npx",
      "args": ["mcpu-client"],
      "env": {
        "SERIAL_PORT": "/dev/ttyACM0"
      }
    }
  }
}

OpenCode

Edit opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcpu": {
      "type": "local",
      "command": ["npx", "mcpu-client"],
      "enabled": true,
      "environment": {
        "SERIAL_PORT": "/dev/ttyACM0"
      }
    }
  }
}

Note

OpenCode uses "environment" (not "env") and "command" must be an array.

---

Custom Baud Rate

The default baud rate is 115200. If your project uses a different rate:

SERIAL_PORT=/dev/ttyACM0 SERIAL_BAUD=9600 npx mcpu-client

In agent config:

"env": {
  "SERIAL_PORT": "/dev/ttyACM0",
  "SERIAL_BAUD": "9600"
}

---

Multiple Serial Devices

For more than one serial device, use the DEVICES format:

DEVICES=robot:/dev/ttyUSB0:115200,display:/dev/ttyACM0:115200 npx mcpu-client

Format: id:port:baud

See Multi-Device Setup for full details.

---

Common Issues

Device Not Appearing

• Check the USB cable — some charge-only cables don’t carry data
• Try a different USB port — some ports may not provide enough power
• Check if it’s detected: ls /dev/tty* before and after plugging in

Wrong Baud Rate

If you see garbled output in Serial Monitor, verify the baud rate matches what your firmware uses (default 115200).

Port In Use

Another application may be holding the port:

# Linux
lsof /dev/ttyACM0

Close any other Serial Monitor instances or Arduino IDE upload windows.

---

Next Steps

• Add a Sensor or Peripheral — wrap sensors in custom tools
• Connect via WiFi TCP — for wireless connections
• Debug Connection Issues — troubleshooting guide