serio-mcp

serio-mcp is a high-performance Model Context Protocol (MCP) server that equips AI assistants (Claude Desktop, Cursor, Antigravity, VS Code) with reliable, zero-loss Serial / UART communication capabilities.

Engineered specifically for embedded Linux development, hardware debugging, router recovery (U-Boot / Bootloader), and IoT automation, featuring a dedicated Expect State-Machine Engine and a continuous background ingestion daemon to eliminate race conditions and dropped bytes.

✨ Features

• ⚡ Zero-Loss Background Daemon: A dedicated reader thread continuously ingests serial streams in the background—ensuring no characters or early bootlogs are dropped between tool calls.
• 🎯 Atomic Expect Engine (serial_expect): Match multiple regular expressions or substring prompts (e.g. ['~ #', 'login:', 'Password:', 'IPQ807x#']) in real-time.
• 🚀 Prompt-Aware Execution (serial_exec_expect): Send shell/bootloader commands and automatically wait for the prompt to return, returning clean, isolated output.
• 🔌 Dynamic Port Discovery & Switching: Enumerate all attached hardware devices with VID/PID and switch ports or baud rates on the fly without restarting the server.
• ⌨️ Raw Control Sequence Support: Send Ctrl+C (\x03), Enter (\r\n), break signals, and custom byte sequences.
• 🛡️ Cross-Platform: Supports Linux, macOS, and Windows.

📦 Installation

Quick Start with uvx (Recommended)

No manual installation required! Run directly with uvx:

uvx serio-mcp

Installation with pip / pipx

pipx install serio-mcp
# or
pip install serio-mcp

⚙️ Configuration

1. Claude Desktop

Add this to your claude_desktop_config.json:

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

{
  "mcpServers": {
    "serio": {
      "command": "uvx",
      "args": ["serio-mcp"]
    }
  }
}

2. Cursor IDE

Add to .cursor/mcp.json or Global Cursor Settings:

{
  "mcpServers": {
    "serio": {
      "command": "uvx",
      "args": ["serio-mcp"]
    }
  }
}

3. Antigravity / Google AI Assistant

Add to ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "serio": {
      "command": "uvx",
      "args": ["serio-mcp"]
    }
  }
}

🛠️ Available MCP Tools

💡 Practical Examples

1. Intercepting U-Boot Bootloader

// Tool call: serial_expect
{
  "patterns": ["IPQ807x#", "Hit any key to stop autoboot:"],
  "command": " ",
  "timeout": 15.0
}

2. Handling Login Prompts

// Step 1: Send username on login prompt
{
  "patterns": ["Password:", "# "],
  "command": "root",
  "timeout": 5.0
}

// Step 2: Send password on Password prompt
{
  "patterns": ["~ #", "# "],
  "command": "admin",
  "timeout": 5.0
}

3. Executing Shell Command

// Tool call: serial_exec_expect
{
  "command": "uname -a; ifconfig br0",
  "timeout": 5.0
}

🧪 Development & Testing

# Clone the repository
git clone https://github.com/weyou/serio-mcp.git
cd serio-mcp

# Set up virtual environment with uv
uv venv
source .venv/bin/activate

# Install in editable mode with development dependencies
uv pip install -e ".[dev]"

# Run tests
pytest -v

# Run linting
ruff check .

📄 License

This project is licensed under the MIT License.