Uart MCP

🚀 UART MCP Server

A MCP Server that provides serial communication capabilities for AI assistants.

✨ Features

• Serial Port Management - Enumerate, open, close, and configure serial port devices.
• Data Communication - Support data transmission and reception in text and binary modes.
• Terminal Session - Create interactive terminal sessions, supporting command sending and output reading.
• Hot Configuration - Support modifying configuration parameters without closing the serial port.
• Auto Reconnection - Automatically attempt to reconnect after the device is disconnected.

🚀 Quick Start

Prompt Configuration

To encourage the AI assistant to prioritize using the UART tool for serial port operations, it is recommended to add the following content to the project prompt file:

Always use the uart MCP tool for serial port operations, including listing serial ports, opening/closing serial ports, sending/receiving data, etc.

The locations of prompt files for different tools:

Claude Code

claude mcp add uart -- uvx --from git+https://github.com/donnel666/uart-mcp.git uart-mcp

Codex CLI

Add the following to ~/.codex/config.toml:

[mcp_servers.uart]
type = "stdio"
command = "uvx"
args = ["--from", "git+https://github.com/donnel666/uart-mcp.git", "uart-mcp"]

Factory Droid

Add the following to the project .factory/settings.json or the global ~/.factory/settings.json:

{
  "mcpServers": {
    "uart": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/donnel666/uart-mcp.git", "uart-mcp"]
    }
  }
}

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "uart": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/donnel666/uart-mcp.git", "uart-mcp"]
    }
  }
}

💻 Available Tools

Serial Port Management

Data Communication

Terminal Session

🔧 Serial Port Permissions

Ensure that this tool has permission to access the serial port device:

Linux:

# Method 1: Temporarily grant permissions
sudo chmod 777 /dev/ttyUSB0

# Method 2: Add the user to the dialout group (recommended, takes effect after re-login)
sudo usermod -aG dialout $USER

macOS:

# Add the user to the wheel group
sudo dseditgroup -o edit -a $USER -t user wheel

Windows: Normally, no additional configuration is required, and COM ports are accessible by default.

💻 Usage Examples

Basic Serial Communication

1. Use list_ports to view available serial ports.
2. Use open_port to open a serial port, such as /dev/ttyUSB0 or COM1.
3. Use send_data to send data.
4. Use read_data to read the response.
5. Use close_port to close the serial port.

Terminal Session Mode

1. Use open_port to open a serial port.
2. Use create_session to create a terminal session.
3. Use send_command to send a command.
4. Use read_output to read the command output.
5. Use close_session to close the session.

📚 Serial Port Configuration Parameters

📚 Configuration Files

The configuration files for UART MCP are located at:

• Linux/macOS: ~/.uart-mcp/
• Windows: %APPDATA%\.uart-mcp\

Configuration File Description

Example of config.toml

[serial]
baudrate = 115200
bytesize = 8
parity = "N"
stopbits = 1.0

[timeout]
read_timeout = 1000
write_timeout = 1000

[flow_control]
xonxoff = false
rtscts = false
dsrdtr = false

[reconnect]
auto_reconnect = true
reconnect_interval = 5000

[logging]
log_level = "INFO"

Example of blacklist.conf

# Blacklist configuration (one rule per line)
# Supports exact matching and regular expressions

# Exact matching
/dev/ttyS0

# Regular expression to match all COM ports
COM[0-9]+

⚠️ Important Note

The permissions of the configuration file should be 600 (readable and writable only by the owner), otherwise, a permission error will be reported.

🛠️ Local Development

# Clone the repository
git clone https://github.com/donnel666/uart-mcp.git
cd uart-mcp

# Install dependencies
uv sync --dev

# Run the server
uv run uart-mcp

# Run tests
uv run pytest

# Code checking
uv run ruff check src/
uv run mypy src/

📋 System Requirements

• Python 3.13+
• Supported operating systems: Linux, macOS, Windows

📄 License

MIT License