Control virtual serial ports over MCP

pdcomm-vserial-mcp is a Model Context Protocol (MCP) server. Through it, AI tools such as Claude Code and Cursor create virtual serial labs, inject faults, and stop them, which helps when you test serial communication code together with an AI assistant.

The server exchanges newline-delimited JSON-RPC messages over standard input and output (stdio) and supports protocol versions 2025-11-25, 2025-06-18, and 2024-11-05. One server runs one lab at a time. When the AI tool disconnects and closes the input, the running lab stops too.

Tools

Tool	Arguments	Result
vserial_validate	config: a lab JSON object	{"valid":true}
vserial_start	config: a lab JSON object	{"ports":[…]}, with the path or address an application opens for each port
vserial_ports	None	{"ports":[…]} of the running lab
vserial_inject	node, fault	{"injected":true}
vserial_attach	node, attached	{"attached":false} or {"attached":true}
vserial_stop	None	{"stopped":true}

config has the same format as a lab file. fault takes the same values as the command-line inject: "drop", {"xor": n}, {"error": "parity"}, and so on. A relative trace path starts at the MCP server’s working directory.

When a tool fails, its result has isError: true and the cause as text, for example a lab is already running; stop it first or no lab is running. Calling a tool that doesn’t exist returns JSON-RPC error -32602 (Unknown tool: <name>).

Connect an AI tool

These examples assume the server is at /opt/pdcomm-vserial/bin/pdcomm-vserial-mcp. Replace the path with yours.

Claude Code

claude mcp add --transport stdio pdcomm-vserial -- /opt/pdcomm-vserial/bin/pdcomm-vserial-mcp

Run claude mcp list, or type /mcp in a session, to check the connection.

Other MCP clients

Add this to the configuration file of any client that supports the stdio transport:

{
  "mcpServers": {
    "pdcomm-vserial": {
      "command": "/opt/pdcomm-vserial/bin/pdcomm-vserial-mcp",
      "args": []
    }
  }
}

Example

Ask your AI tool something like this:

Start a 19200 bit/s even-parity null-modem pair with links /tmp/pdcomm-plc and /tmp/pdcomm-hmi, then inject one framing error into the hmi port.

The tool calls vserial_start and then vserial_inject. The result of vserial_start looks like this:

{"ports":[{"backend":"pty","link":"/tmp/pdcomm-plc","node":"plc","path":"/dev/ttys011"},{"backend":"pty","link":"/tmp/pdcomm-hmi","node":"hmi","path":"/dev/ttys016"}]}

The pseudo terminal ports exist on the computer that runs the MCP server, so run your application on that computer too. When you finish, ask the AI tool to stop the lab (vserial_stop).