Skip to main content
Glama
MCP Remote Access
by RFingAdam

Authorized security testing only. See DISCLAIMER.md.


License Python 3.10+ MCP eng-mcp-suite

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


What is mcp-remote-access?

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.


Related MCP server: MCP SSH Server with Streamable HTTP

Quick start

Install

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

Run it

The server speaks MCP over stdio:

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

Add it to an MCP client

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.


Tools

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

SSH (9)

Tool

Purpose

ssh_connect

Connect to a host via SSH (password or key auth)

ssh_execute

Run a command on a connected host (sync)

ssh_execute_background

Run a long-running command async, returns task_id

ssh_check_background

Check status / collect output of a background command

ssh_list_background

List all active background commands

ssh_upload

Upload a file via SFTP

ssh_download

Download a file via SFTP

ssh_disconnect

Close an SSH connection

ssh_list_connections

Show active SSH connections

Serial / UART (17)

Tool

Purpose

serial_list_ports

List available serial ports (with VID/PID, description, serial #)

serial_connect

Connect by port name

serial_connect_match

Connect by VID / PID / serial / description match

serial_esp32_connect

ESP32-aware connect (BOOT/RESET sequence, auto-baud)

serial_send

Send text data (with optional response read + configurable line ending)

serial_send_bytes

Send raw bytes as hex (binary protocols: Nordic DTM, HCI, etc.)

serial_read

Read available data

serial_read_bytes

Read raw bytes back as hex

serial_wait_for

Wait for a pattern in the incoming stream

serial_expect

Wait/send step sequences (login prompts, AT flows)

serial_send_break

Send a break signal

serial_set_dtr

Set DTR line state

serial_set_rts

Set RTS line state

serial_reset_device

Reset device via DTR/RTS sequence

serial_flush

Flush serial buffers

serial_disconnect

Close a serial connection

serial_list_connections

Show active serial connections


Workflows

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.


Documentation


Part of 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:

Domain

Sibling MCPs

RF / Transmission lines

lineforge

EMC regulatory

mcp-emc-regulations

PCB / SI

mcp-pcb-emcopilot (private: public soon)

EM simulation

mcp-openems, mcp-nec2-antenna (private: public soon)

Diagrams

drawio-engineering-mcp

3D / rendering

mcp-blender

Remote access

mcp-remote-access (this repo)

Lab gear

copper-mountain-vna-mcp, mcp-rs-spectrum-analyzer, mcp-rs-siggen, mcp-rs-cmw500


Security notes

  • 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.


Troubleshooting

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.


Contributing

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.


License

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.

Brand assets

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.

Acknowledgments

Part of eng-mcp-suite.

Available Tools

24 tools
serial_connectC

Connect to a serial port. Returns a connection ID.

Inputs: port (required), baudrate, timeout.

serial_connect_matchB

Connect to a serial port by matching VID/PID/serial/description. Returns a connection ID.

Inputs: vid, pid, serial_number, description_contains, +4 more.

serial_disconnectC

Close a serial port connection.

Inputs: connection_id (required).

serial_esp32_connectA

Connect to ESP32 with automatic reset and boot wait. Handles the ESP32 boot sequence (74880 baud boot messages, then app at 115200). Resets the device and waits for it to be ready.

Inputs: port (required), baudrate, reset, wait_for_boot, +2 more.

serial_expectC

Wait for patterns and optionally send responses. Useful for login prompts and AT flows.

Inputs: connection_id (required), steps (required), flush_input, default_timeout, +1 more.

serial_flushA

Flush serial buffers (clear pending input/output data).

Inputs: connection_id (required), input, output.

serial_list_connectionsB

List all active serial connections.

Inputs: no named parameters.

serial_list_portsB

List available serial ports on the system.

Inputs: no named parameters.

serial_readC

Read available data from a serial port.

Inputs: connection_id (required), timeout, bytes.

serial_reset_deviceA

Reset an embedded device using DTR/RTS sequence. Supports ESP32, STM32, and generic reset.

Inputs: connection_id (required), method.

serial_sendB

Send data to a serial port. Optionally wait for and return response.

Inputs: connection_id (required), data (required), raw, line_ending, +2 more.

serial_send_breakA

Send a serial break signal. Used to interrupt U-Boot, enter debug modes.

Inputs: connection_id (required), duration.

serial_set_dtrB

Set DTR (Data Terminal Ready) line state. Used for device reset on many boards.

Inputs: connection_id (required), state (required).

serial_set_rtsB

Set RTS (Request To Send) line state. Used for bootloader entry on ESP32/STM32.

Inputs: connection_id (required), state (required).

serial_wait_forB

Wait for a specific string/pattern in serial output. Useful for boot messages, prompts.

Inputs: connection_id (required), pattern (required), timeout.

ssh_check_backgroundA

Check status and get output from a background command. Returns whether it's still running and the latest output.

Inputs: task_id (required), tail_lines.

ssh_connectA

Connect to a remote host via SSH. Returns a connection ID for subsequent commands.

Inputs: host (required), username (required), password, key_path, +1 more.

ssh_disconnectC

Close an SSH connection.

Inputs: connection_id (required).

ssh_downloadB

Download a file from the remote host via SFTP.

Inputs: local_path (required), remote_path (required), connection_id (required).

ssh_executeB

Execute a command on a connected SSH host. Returns stdout, stderr, and exit code.

Inputs: connection_id (required), command (required), timeout.

ssh_execute_backgroundA

Execute a long-running command in the background. Returns a task ID and output file path. Use ssh_check_background to monitor progress.

Inputs: command (required), connection_id (required).

ssh_list_backgroundB

List all background tasks and their status.

Inputs: no named parameters.

ssh_list_connectionsB

List all active SSH connections.

Inputs: no named parameters.

ssh_uploadB

Upload a file to the remote host via SFTP.

Inputs: local_path (required), remote_path (required), connection_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 24 tools

    Disambiguation4/5

    The SSH and serial tool groups are clearly separated by prefix, and within each group the actions are distinct (connect, execute, disconnect, list, etc.). The only minor ambiguity is between serial_expect and serial_wait_for, which both wait for patterns, though expect adds optional response sending.

    Naming Consistency4/5

    Most tools follow a consistent transport_verb pattern (ssh_connect, serial_send, serial_disconnect). Minor deviations include serial_connect_match and serial_esp32_connect, which are more specific but still readable and consistent with the overall convention.

    Tool Count4/5

    24 tools is on the higher end but justified by covering two distinct transports (SSH and serial) with connection lifecycle, data operations, and device-specific helpers. A few tools like serial_flush and serial_read could potentially be merged, but the count is not excessive for the scope.

    Completeness4/5

    The tool set covers the full lifecycle for both SSH (connect, execute, background, upload/download, disconnect) and serial (connect, send, read, expect, reset, disconnect). Minor gaps include no SSH port forwarding or serial line settings (baud/parity) configuration, but core remote access workflows are well covered.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers