MCP server allowing Agents to talk to devices connected to serial port of the computer. Tested only with MAC atm.
A robust serial communication server built with FastMCP framework, providing a reliable interface for serial port communication with features like message buffering, error handling, and connection management.
- Clone the repository:
git clone https://github.com/PaDev1/Serial-MCP.git
cd Serial-MCP- Install dependencies:
pip install -r requirements.txtAdd the server after installing to your Claude Desktop or similar with the following structure
"serial_MCP": { "command": "uv", "args": [ "run", "--with", "fastmcp,pyserial", "fastmcp", "run", "/serial_MCP.py" ], "env": { "SERIAL_PORT": "", "SERIAL_BAUD_RATE": "9600", "SERIAL_BUFFER_LENGTH": "100" } }
- Asynchronous Serial Communication: Built on asyncio for efficient I/O operations
- Message Buffering: Configurable buffer size with timestamp support
- Connection Management: Automatic port detection and connection handling
- Error Handling: Comprehensive error detection and reporting
- Environment Configuration: Support for environment variables and runtime configuration
- Logging: Detailed logging with timestamps and error tracking
Wait for a specified number of seconds.
Parameters:
delay(float): Number of seconds to wait (must be positive)
Returns:
- Success status
- Requested delay time
- Actual delay time (measured)
- Status message
Example:
await delay({
"delay": 2.5 # Wait for 2.5 seconds
})Initialize a serial connection with specified parameters.
Parameters:
port(str): Serial port device path (e.g., '/dev/tty.usbmodem1101')baudrate(int): Communication speed in bauds (default: 9600)buffer_length(int): Maximum number of messages to buffer (default: 100)
Returns:
- Status of initialization
- Current mode (real/disconnected)
- Port and baudrate information
Send a message through the serial connection and optionally wait for a response.
Parameters:
message(str): Message to sendwait_for_response(bool): Whether to wait for a response after sending (default: False)response_timeout(float): Time in seconds to wait for a response (default: 0.5)
Returns:
success(bool): Overall operation successstatus(str): Operation status ("success", "error", etc.)mode(str): Current connection mode ("real", "disconnected")write_status(str): Write operation status:- "success": Message was written successfully
- "failed": Write operation failed
- "timeout": Write operation timed out
connection_state(str): Current connection state:- "connected": Serial port is connected and available
- "disconnected": No active serial connection
- "error": Connection in error state
response_status(str): Response status:- "not_checked": Response check was not requested
- "received": Response was received
- "no_response": No response received within timeout
- "error": Error occurred while checking for response
response_messages(list): List of received messages (if any)bytes_written(int): Number of bytes successfully writtenerror_type(str): Type of error if operation failedmessage(str): Human-readable status messageerror_details(dict): Additional error information if applicable
Example Send Without Response Check:
await send_message({
"message": "Hello",
"wait_for_response": False
})
# Returns:
{
"success": True,
"status": "success",
"mode": "real",
"write_status": "success",
"connection_state": "connected",
"response_status": "not_checked",
"response_messages": [],
"bytes_written": 6,
"message": "Message sent successfully in real mode"
}Example Send With Response Check:
await send_message({
"message": "Hello",
"wait_for_response": True,
"response_timeout": 1.0
})
# Returns:
{
"success": True,
"status": "success",
"mode": "real",
"write_status": "success",
"connection_state": "connected",
"response_status": "received",
"response_messages": [
{
"timestamp": "2024-03-14T15:30:45.123456",
"message": "Hello received"
}
],
"bytes_written": 6,
"message": "Message sent successfully in real mode"
}Example No Response Within Timeout:
await send_message({
"message": "Hello",
"wait_for_response": True,
"response_timeout": 0.5
})
# Returns:
{
"success": True,
"status": "success",
"mode": "real",
"write_status": "success",
"connection_state": "connected",
"response_status": "no_response",
"response_messages": [],
"bytes_written": 6,
"message": "Message sent successfully in real mode"
}Read messages from the buffer.
Parameters:
wait(bool): Whether to wait for messages if buffer is empty (default: False)timeout(float): Time to wait for messages in seconds (default: 1.0)
Returns:
- List of messages with timestamps
- Current mode
- Status of read operation
List all available serial ports on the system.
Parameters: None
Returns:
- List of available ports with details
- Port names and descriptions
- Hardware IDs
Get the current status of the serial connection.
Parameters: None
Returns:
- Current mode
- Port and baudrate information
- Buffer length
- Available ports
- Last error message
- Serial module availability
Configure the serial connection after initialization.
Parameters:
port(str, optional): New port to usebaudrate(int, optional): New baudrate to uselist_ports(bool): Whether to just list ports (default: False)
Returns:
- Updated configuration
- Current mode
- Available ports (if list_ports is True)
Close the current serial connection.
Parameters: None
Returns:
- Status of closure
- Current mode
Get detailed instructions on how to use the Serial MCP server.
Parameters: None
Returns:
- Detailed help information including:
- Tool descriptions and parameters
- Example usage for each tool
- Common response formats
- Connection states
- Response statuses
- Important usage notes
Example:
await help()
# Returns comprehensive help information about all available tools and their usageThe server can be configured using environment variables:
SERIAL_PORT: Serial port device path (default: '/dev/tty.usb*')SERIAL_BAUD_RATE: Communication speed in bauds (default: 9600)SERIAL_BUFFER_LENGTH: Maximum number of messages to buffer (default: 100)
python serial_MCP.pyawait init_serial({
"port": "/dev/tty.usbmodem1101",
"baudrate": 9600,
"buffer_length": 100
})await send_message({
"message": "Hello, device!"
})await read_message({
"wait": False, # Whether to wait for messages
"timeout": 1.0 # Timeout in seconds
})await list_serial_ports()await get_serial_status()await configure_serial({
"port": "/dev/tty.usbmodem1101",
"baudrate": 9600,
"list_ports": False
})await close_serial()Messages in the buffer are stored with timestamps:
{
"timestamp": "2024-03-14T15:30:45.123456", # ISO format
"message": "Actual message content"
}The server provides detailed error messages for various scenarios:
- Connection failures
- Invalid parameters
- Timeout conditions
- Buffer overflow
- Invalid messages
Logs are written to logs/serial_MCP.log with the following format:
[timestamp] - [level] - [message]
- Python 3.7+
- pyserial>=3.5
- fastmcp>=0.1.0
- pydantic>=2.0.0
- asyncio>=3.4.3
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- FastMCP framework for the server infrastructure
- pyserial for the serial communication capabilities