MecoSerial

Features

• Overview window listing /dev/cu.* serial adapters under USB and Bluetooth
• Per-device settings (baud rate, data bits, parity, stop bits, flow control) that persist across launches
• Profiles for reusable line settings across devices — built-in Generic (115200) and Rockchip Preset (1500000), plus custom profiles
• Separate connection window per adapter — connect manually with Start
• Fixed top bar with baud rate control, Start/Stop serial connection, terminal clear, and session logging (save on stop)
• Baud presets up to 1.5 Mbps plus manual entry (commits on Enter, focus loss, or preset pick)
• Ghostty terminal surface for fast VT100/xterm rendering

Requirements

• macOS 13+
• Xcode 16+

Build

Xcode

1. Open MecoSerial.xcodeproj in Xcode.
2. Resolve Swift Package dependencies when prompted.
3. Build and run the MecoSerial scheme.

Command line

From the repository root:

# Resolve Swift Package dependencies
xcodebuild -resolvePackageDependencies \
  -project MecoSerial.xcodeproj \
  -scheme MecoSerial

# Debug build
xcodebuild \
  -project MecoSerial.xcodeproj \
  -scheme MecoSerial \
  -configuration Debug \
  -destination 'platform=macOS' \
  build

# Release build
xcodebuild \
  -project MecoSerial.xcodeproj \
  -scheme MecoSerial \
  -configuration Release \
  -destination 'platform=macOS' \
  build

The built app is written to Xcode DerivedData, for example:

~/Library/Developer/Xcode/DerivedData/MecoSerial-*/Build/Products/Debug/MecoSerial.app

To build and launch the Debug app in one step:

xcodebuild \
  -project MecoSerial.xcodeproj \
  -scheme MecoSerial \
  -configuration Debug \
  -destination 'platform=macOS' \
  build && \
open "$(find ~/Library/Developer/Xcode/DerivedData/MecoSerial-* \
  -path '*/Build/Products/Debug/MecoSerial.app' \
  -type d | head -1)"

The app is intentionally not sandboxed so it can open local serial device nodes.

Usage

1. Launch MecoSerial to see connected serial adapters grouped by USB and Bluetooth.
2. Click the gear on a row (or use Settings… in the context menu) to set baud rate and line settings for that device. Settings are remembered per device path.
3. In device settings, pick a Profile (Generic 115200 or Rockchip Preset 1500000) to fill line settings instantly, or use Save as Profile… to store the current settings for other devices. Manage custom profiles in MecoSerial → Settings….
4. Click Open (or double-click a row) to open a terminal window — the port stays disconnected until you press Start.
5. Adjust baud from the top bar; pick a preset or type any rate from 1 to 1,500,000 (applied on Enter, click-away, or preset selection). Baud changes in the connection window are also saved for that device.
6. Use Stop / Start to close or reopen the serial port without closing the window.
7. Use Clear Terminal to clear the Ghostty surface without closing the serial port.
8. Use Start Logging to capture received console output in memory, then Stop Logging to choose a file and save the transcript.

MCP integration (Cursor / Claude)

MecoSerial exposes open serial sessions to AI agents through a bridge MCP server. The app owns the UART; the MCP CLI forwards tool calls over a local Unix socket.

Requirements

1. MecoSerial must be running — the bridge listens at ~/Library/Application Support/MecoSerial/bridge.sock.
2. Build the MCP CLI once:

./Scripts/build-mcp.sh release

This prints the path to meco-serial-mcp, for example:

/Users/you/Documents/GitHub/MecoSerial/mcp/.build/release/meco-serial-mcp

Cursor setup

Add to your project .cursor/mcp.json (see .cursor/mcp.json.example):

{
  "mcpServers": {
    "meco-serial": {
      "command": "/absolute/path/to/meco-serial-mcp"
    }
  }
}

Restart Cursor or reload MCP servers in Settings → Tools & MCP.

Available tools

Tool	Purpose
ping	Verify the app bridge is reachable
list_ports	Enumerate /dev/cu.* adapters
list_sessions	List open terminal sessions in the app
open_session	Open a port in the MecoSerial UI
connect / disconnect	Start or stop the serial link
write / write_hex	Send data to the device
read / wait_for	Read from the MCP RX buffer
apply_settings	Change baud and line settings
session_status	Connection state and buffer size

Identify a session with session_id (from list_sessions) or port_path (e.g. /dev/cu.usbserial-110).

Notes

• MCP traffic shares the same live session as the Ghostty terminal — RX still appears in the UI.
• The MCP server does not open serial ports on its own; exclusive access stays with MecoSerial.
• Tool names use underscores for Cursor compatibility.

Author

Mecid Urganci

License

MIT — see LICENSE.