MCP2Serial

You will learn how to connect serial devices to AI models using MCP, enabling natural language control and real-time hardware parameter adjustments through the MCP framework.

How to use

You interact with MCP2Serial through an MCP client. Start by ensuring your client is configured to talk to the MCP2Serial server, then issue natural language commands or prompts that the MCP will interpret and forward to your serial device. You can control a PWM setting, read device status, and trigger actions by mapping your prompts to the commands defined in your config. If you enable loopback mode for testing, you can send commands directly and observe their echoed responses. When the server receives a command, it communicates with your serial device using the configured port, baud rate, and timeout settings, then returns the result to your MCP client.

How to install

Prerequisites: you need Python and a valid MCP client installed on your machine. Optional but recommended: a Python virtual environment and an MCP client such as Claude Desktop or Cline.

# Windows
# Installation steps assume you have Python installed
python install.py

# macOS
curl -O https://raw.githubusercontent.com/mcp2everything/mcp2serial/main/install_macos.py
python3 install_macos.py

# Ubuntu / Raspberry Pi
curl -O https://raw.githubusercontent.com/mcp2everything/mcp2serial/main/install_ubuntu.py
python3 install_ubuntu.py

If you prefer to install dependencies manually, run these minimal setup steps which rely on the uv tool and your MCP client being present.

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"  # Windows
curl -LsSf https://astral.sh/uv/install.sh | sh  # macOS/Linux

Configuration and usage notes

Create or edit a configuration file named config.yaml to specify how MCP2Serial talks to your serial device and what commands your MCP prompts map to. The following shows a basic setup using a simulated loopback serial port for testing. You can switch to a real port like COM11 or /dev/ttyUSB0 when hardware is connected.

serial:
  port: LOOP_BACK  # use LOOP_BACK for simulation, or specify a real port like COM11
  baud_rate: 115200
  timeout: 1.0
  read_timeout: 1.0
  response_start_string: CMD

commands:
  set_pwm:
    command: "CMD_PWM {frequency}"
    need_parse: false
    prompts:
      - "把PWM调到最大"
      - "把PWM调到最小"
      - "请将PWM设置为{value}"
      - "关闭PWM"
      - "把PWM调到一半"

Multiple MCP server configurations

You can run multiple MCP2Serial instances with different configurations. For example, you can load a Pico configuration file named Pico_config.yaml for one device and a second device with Pico2_config.yaml for another. Each running instance must use a separate MCP URL/command as shown in their respective startup instructions.

# Pico configuration
{
  "mcpServers": {
    "mcp2serial": {
      "command": "uvx",
      "args": [
        "mcp2serial",
        "--config",
        "Pico"  # specify Pico_config.yaml without _config.yaml suffix
      ]
    }
  }
}

# Pico2 configuration
{
  "mcpServers": {
    "mcp2serial2": {
      "command": "uvx",
      "args": [
        "mcp2serial",
        "--config",
        "Pico2"  # specify Pico2_config.yaml without _config.yaml suffix
      ]
    }
  }
}

Starting the server and using the client

To start the server in a development setup that uses a simulated loopback port, you can run the following command in your terminal after activating your Python virtual environment.

uv run src/mcp2serial/server.py
# or
uv run mcp2serial

Hardware and firmware notes

Connect your device via USB to your computer. Identify the COM port in your device manager and configure the matching port and baud rate in config.yaml. If you are using Pico hardware, you can load Micropython firmware as part of your prototype workflow.

Troubleshooting and tips

If a command does not seem to execute, verify that the serial port is correct and that the device responds within the configured read_timeout. For testing, use LOOP_BACK to validate command and response flow, but remember to adjust response_start_string to match the simulated responses.

Available tools

MCP protocol integration

Provides full support for the Model Context Protocol within the server, enabling resource management, tool calls, and a flexible prompting system.