UART

Provides a UART MCP server that enumerates, opens, configures, and communicates with serial ports for text and binary data.

python

3

GitHub Stars

python

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

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

The UART MCP Server gives your AI assistants direct, programmable access to serial ports. It can enumerate ports, open and configure them, send and receive data in text or binary modes, run interactive terminal sessions, adjust settings on the fly, and automatically reconnect when a device reappears. This makes it easy to build conversational or automated flows that communicate with UART devices.

How to use

You interact with the UART MCP Server through an MCP client that speaks the MCP protocol. Use the provided tools to list available ports, open a port with your desired settings, send and receive data, and, when needed, create an interactive terminal session to issue commands and read outputs. You can adjust port configurations without closing the port and rely on automatic reconnection when a device disconnects.

How to install

Prerequisites: ensure you have Python 3.13 or higher and the MCP runtime available in your environment.

Clone the UART MCP Server repository.

git clone https://github.com/donnel666/uart-mcp.git
cd uart-mcp

Install dependencies for development and runtime.

uv sync --dev

Start the UART MCP Server.

uv run uart-mcp

Configuration and usage notes

Configure the server to control UART devices through the provided configuration files. You will typically work with two files located under your user directory:

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

Configuration details include the global defaults for baud rate, data bits, parity, stop bits, and timeouts, as well as a blacklist for ports you want to exclude. Use a TOML file for global settings and a separate file for the blacklist.

Security and permissions

Ensure the running process has permission to access the serial ports on your system. On Linux, you may need to adjust user permissions or group membership so that the process can open /dev/tty* devices.

On macOS and Windows, ensure the user account has the necessary privileges to access the serial interfaces you plan to use.

Troubleshooting tips

If a device disconnects, the server will attempt to reconnect automatically. If you encounter port access errors, double-check your port name, permissions, and that the port is not in use by another application.

Examples of common workflows

Baseline UART communication workflow:

Use the client to list ports
Open a port with your desired settings
Send data or read responses
Close the port when finished

Terminal session workflow:

Open a port
Create a session
Send commands and read outputs
Close the session and port

Available tools

list_ports

Enumerates all available serial port devices.

open_port

Opens a specified serial port with configurable parameters such as baud rate, data bits, parity, and stop bits.

close_port

Closes a previously opened serial port.

set_config

Dynamically updates an open port's configuration without closing it (hot update).

get_status

Retrieves current port status and configuration.

send_data

Sends data to the serial port in text or binary mode.

read_data

Reads data from the serial port in text or binary mode.

create_session

Creates an interactive terminal session with configuration for line endings and local echo.

close_session

Closes an active terminal session.

send_command

Sends a command to an active terminal session.

read_output

Reads the output buffer from a terminal session.

list_sessions

Lists all active terminal sessions.

get_session_info

Retrieves detailed information about a specific session.

clear_buffer

Clears the session output buffer.