RFingAdam/mcp-remote-access: MCP server for SSH and Serial port remote access · GitHub

⚠️ Authorized security testing only. See DISCLAIMER.md.

SSH and serial-port control for embedded devices, exposed as MCP tools. Log into a Raspberry Pi, talk to a UART, drive a USB-CDC console from your assistant.

Quick start · Tools · Workflows · Documentation

mcp-remote-access is an MCP server that exposes SSH (over paramiko) and serial / UART (over pyserial) as MCP tools. Once it's running, an agent can log into a host over SSH, run commands, transfer files, open a serial console, send AT-style command sequences, and reset a device over DTR/RTS.

It's deliberately thin: 26 tools, two transports, no orchestration language. Higher-level workflow logic lives in the agent's prompts, not in this server.

A few things it handles that are easy to get wrong by hand:

• Connect to a serial port by VID/PID/serial number/description instead of guessing /dev/ttyUSB0 vs /dev/ttyUSB1 (serial_connect_match).
• Long-running SSH commands (builds, tcpdump, test runs) don't block the MCP channel: ssh_execute_background returns a task ID, ssh_check_background polls it.
• serial_expect/serial_wait_for wait for a real pattern in the stream instead of a fixed sleep(), which avoids the usual "sent before the prompt was ready" race on login prompts and AT flows.
• DTR/RTS control for hard-resetting MCUs over USB-serial, plus break-signal support.
• SSH passwords are held in memory only and cleared on disconnect; no on-disk session store.

git clone https://github.com/RFingAdam/mcp-remote-access.git
cd mcp-remote-access
uv pip install -e .

The server speaks MCP over stdio:

uv run --directory /path/to/mcp-remote-access mcp-remote-access

Codex CLI:

codex mcp add remote-access -- \
  uv run --directory /path/to/mcp-remote-access mcp-remote-access

Claude Code:

claude mcp add remote-access -- \
  uv run --directory /path/to/mcp-remote-access mcp-remote-access

Or add it to a client config file directly:

{
  "mcpServers": {
    "remote-access": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-remote-access", "mcp-remote-access"]
    }
  }
}

Then, from the assistant:

"Connect to my Pi at vpn-ap.local as pi (password raspberry), run uname -a, then dmesg | tail -20."

That's ssh_connect followed by two ssh_execute calls.

26 MCP tools across two transports. Full reference in docs/tools.md.

mcp-remote-access fits in the following eng-mcp-suite workflow bundles:

• lab-automation: pair with mcp-rs-spectrum-analyzer, mcp-rs-siggen, copper-mountain-vna-mcp to fully script a bench (DUT login over SSH or UART, lab gear over SCPI).
• embedded-bringup: serial_connect_match + serial_expect + ssh_upload for boot-loader interaction and image flashing.

Part of eng-mcp-suite. Use in the lab-automation workflow bundle.

See the suite manifest for the full list of sibling MCPs and bundle definitions.

• Quick Start: install through first call.
• Tool reference. Every MCP tool, every argument.
• Usage examples: practical end-to-end walkthroughs.
• Architecture: how this MCP fits in eng-mcp-suite.

This server is one piece of eng-mcp-suite, an umbrella of engineering MCP servers covering RF, EMC, PCB, signal integrity, EM simulation, and lab test. See the full catalog or jump to a sibling:

• SSH passwords are kept in memory only and cleared on server restart.
• Connections are session-scoped; the server does not persist a session store on disk.
• Use SSH keys where possible.
• The MCP server runs over stdio. It only accepts connections from the local MCP client, never from the network.

SSH connection issues: verify the host is reachable (ping vpn-ap.local), that SSH is listening on the target (ssh pi@vpn-ap.local from the same shell), and that credentials are correct.

Serial port issues. Check port permissions (ls -la /dev/ttyUSB*), add your user to the dialout group (sudo usermod -a -G dialout $USER and re-login), and confirm the device is present (dmesg | tail).

VID/PID match selects wrong device: serial_connect_match returns the first hit; pair the match on description or serial_number to disambiguate.

Contributions are welcome.

1. Pick a GitHub issue.
2. Fork + branch (feature/your-thing or fix/your-bug).
3. Run tests (uv run pytest) if present.
4. Open a PR: link the issue, request review.

AGPL-3.0-or-later. Relicensed from Apache-2.0 in v0.2.0 to align with the eng-mcp-suite toolkit-wide AGPL move.

The project name and the logo files in this repository are not part of the licensed work. The licence above grants no permission to use them, except as needed to describe the origin of the work.

• paramiko: SSH transport.
• pyserial: serial / UART transport.
• The MCP working group: for the Model Context Protocol specification.