serial-mcp

# Serial MCP Server    Embedded AI debugging serial MCP service, enabling AI tools like Claude Code/Codex CLI to directly read and write serial data, achieving a complete closed loop of coding, burning, and debugging. ## Function Status | Function | Status | |------|------| | Serial Connection/Disconnection | ✅ Stable | | Data Transmission/Reception | ✅ Stable | | SQLite Data Persistence | ✅ Stable | | Multi-Serial Port Concurrency | ✅ Stable | | Automatic Device Detection | ✅ Stable | | Monitoring Window TUI | ✅ Stable | | Timed Sending | ✅ Stable | | Modbus RTU | 🚧 Under Development | | Web Monitoring Panel | 🚧 Planned | ## Architecture ``` AI (Claude Code / Codex CLI) │ MCP Protocol ▼ ┌─────────────────┐ │ serial-mcp │ MCP Server (9 tools) │ server.js │ └────────┬────────┘ │ HTTP POST localhost:7070 ▼ ┌─────────────────┐ ┌──────────────────┐ │ serial-db │◄──────►│ SQLite │ │ listener.js │ Read/Write │ serial.db │ └────────┬────────┘ └──────────────────┘ │ UART COM3 ▼ ┌─────────────────┐ │ Microcontroller / Virtual │ COM2 ↔ COM3 │ serial-virtual │ └─────────────────┘ ``` ## Features - Real-time reception of serial data, persisted to SQLite - AI actively queries historical data, searching by session/time range - AI sends instructions and waits for responses within 120ms - Supports multiple response boundary modes (timeout/delimiter/length) - Virtual serial port simulator, allowing development and debugging without physical hardware - One-click start/stop script ## Project Structure ``` serial-mcp/ ├── serial-virtual/ Virtual Microcontroller Simulator ├── serial-db/ Serial Port Listener + SQLite Data Pool + HTTP Forwarding Service ├── serial-mcp/ MCP Server ├── start-all.bat One-Click Start ├── stop-all.bat One-Click Stop └── docs/ Project Documentation ``` ## Dependencies - Node.js v18+ - Windows System - Virtual Serial Port Driver (for development and debugging): [ELTIMA VSP](https://www.eltima.com/products/vspdxp/) or [com0com](https://com0com.sourceforge.net) ## Installation ### Windows #### Claude Code (User Level, available for all projects) ```bash claude mcp add -s user serial -- cmd /c npx -y serial-mcp ``` #### Codex CLI ```bash codex mcp add serial -- npx -y serial-mcp ``` ### Mac/Linux #### Claude Code ```bash claude mcp add -s user serial -- npx -y serial-mcp ``` #### Codex CLI ```bash codex mcp add serial -- npx -y serial-mcp ``` ### Verify Installation Success ```bash # Claude Code claude mcp list # Codex CLI codex mcp list ``` See serial status as "connected" to confirm success. ### Uninstallation ```bash # Claude Code claude mcp remove -s user serial # Codex CLI codex mcp remove serial ``` ## Usage After connecting the device, simply tell AI: "My device is connected to COM5, baud rate 115200, help me connect and start debugging" AI will automatically complete the connection without requiring any additional configuration. ## MCP Tool List | Tool | Description | |------|------| | `list_ports` | Scan available serial ports | | `connect_port` | Connect to specified serial port and create a new session | | `disconnect_port` | Disconnect from current serial port | | `send_data` | Send data | | `read_latest` | Read latest N pieces of data | | `read_since` | Read data since specified time | | `send_and_wait` | Send instruction and wait for response | | `new_session` | Create a new session (called after burning) | | `get_status` | Get current serial port status | ## Real Hardware Access 1. Connect the physical device to the computer 2. Execute serial port scanning and connect to the target port in AI 3. Directly start sending/receiving debugging data No manual configuration file modifications required; AI debugging method remains consistent. ## FAQ **Q: Why can't I see COM2/COM3 with list_ports?** A: ELTIMA VSP's virtual port does not use standard WMI enumeration, but actual communication is normal and does not affect usage. **Q: Does it support Linux/Mac?** A: Serial communication part is supported, but start-all.bat is limited to Windows; Linux/Mac requires manual start of each service. **Q: Will the database grow indefinitely?** A: No, it automatically cleans up the oldest data after 10,000 entries; adjustable in `serial-db/config.json` with `maxRows`. **Q: How to distinguish data before and after burning?** A: Call `new_session` to create a new session after burning, then filter data with `session_id`. ## License MIT