Skip to main content

mcp-ssh-wrapper

mcp-ssh-wrapper is a minimal MCP server that executes commands on remote hosts by delegating to the local ssh binary.

The server does not implement SSH authentication. It relies entirely on the host machine's existing SSH configuration, agent, identities, and host key policy.

This project runs as a streamable HTTP MCP server. It is intended to be started as a long-lived local process and then connected to by tools like Codex or Claude.

The SSH execution path is non-interactive. The server runs ssh in batch mode and does not allow prompts on stdin, so hosts must already be reachable using existing SSH config, keys, agent state, and known-hosts entries.

Warning: binding this server to anything other than localhost or 127.0.0.1 exposes a tool that can use the local machine's SSH configuration, agent, and keys over the network. Treat non-local binding as a high-risk configuration.

Features

  • Exposes a single MCP tool: execute_command
  • Uses the system ssh command directly
  • Returns stdout, stderr, and exit_code
  • Supports an optional execution timeout

Installation

pip install mcp-ssh-wrapper

Running the server

After installation, run the server with:

mcp-ssh-wrapper --host 127.0.0.1 --port 8000 --mount-path /mcp

This exposes the MCP endpoint at http://127.0.0.1:8000/mcp.

You can also use the module entrypoint:

python -m mcp_ssh_wrapper --host 127.0.0.1 --port 8000 --mount-path /mcp

Keep this bound to localhost unless you fully understand the security implications.

Local execution

For local development from this repository, use the helper script:

./run_server.sh --host 127.0.0.1 --port 8000 --mount-path /mcp

If your SSH setup depends on ssh-agent, run_server.sh will try to recover SSH_AUTH_SOCK automatically on macOS.

Add to Codex

Start the server first:

mcp-ssh-wrapper --host 127.0.0.1 --port 8000 --mount-path /mcp

Then register the running HTTP endpoint with Codex:

codex mcp add mcp-ssh --url http://127.0.0.1:8000/mcp

Verify the registration:

codex mcp list
codex mcp get mcp-ssh

Codex will connect to the running HTTP endpoint. It does not launch the server process for you in this setup.

Add to Claude

Claude Code CLI

Start the server first, then register the URL with Claude Code:

claude mcp add mcp-ssh --transport http http://127.0.0.1:8000/mcp

Verify the registration:

claude mcp list
claude mcp get mcp-ssh

Claude Desktop

Add this server entry to your claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-ssh": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Claude Desktop will connect to the running local HTTP server.

Important limitation

run_test.sh does not launch the server. Start mcp-ssh-wrapper ... or ./run_server.sh ... first, then run the test wrapper against the live endpoint.

Local smoke test

To verify startup, MCP initialization, and tool discovery against a running server:

./run_test.sh --skip-call

To target a non-default endpoint:

./run_test.sh --url http://127.0.0.1:8000/mcp --skip-call

To also invoke the SSH tool:

./run_test.sh --host my-host --command "uname -a"

Tool

execute_command

Arguments:

  • host: SSH host or user@host, resolved by the local SSH client
  • command: Command string to execute remotely
  • timeout_seconds: Optional timeout. 0 disables timeout handling.

Result:

{
  "host": "prod-box",
  "command": "uname -a",
  "stdout": "Linux ...\n",
  "stderr": "",
  "exit_code": 0
}

Notes

  • SSH options should be configured in ~/.ssh/config or the host environment.
  • This server invokes ssh -o BatchMode=yes, so password prompts and interactive confirmations are disabled.
  • Authentication, host key policy, and identity selection are still handled by the local ssh client and its existing configuration.

Releasing

This project is configured to publish to PyPI using GitHub Trusted Publishing via .github/workflows/publish-pypi.yml.

Release flow:

  1. Update project.version in pyproject.toml.
  2. Commit the version bump and push it to main.
  3. Tag the main commit with a matching version tag in the form vX.Y.Z.
  4. Push the tag to GitHub.

Example for version 0.1.0:

git checkout main
git pull
git tag v0.1.0
git push origin v0.1.0

The GitHub Actions workflow will:

  • verify the tag points to a commit on main
  • verify the tag matches project.version
  • build the package
  • publish it to PyPI using the GitHub pypi environment

Metadata

Release files for mcp-ssh-wrapper 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mcp-ssh-wrapper 0.1.1
File Size Uploaded Provenance Actions
mcp_ssh_wrapper-0.1.1.tar.gz 50.7 kB With provenance Details for mcp_ssh_wrapper-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mcp-ssh-wrapper 0.1.1
File Interpreter ABI Platform Actions
mcp_ssh_wrapper-0.1.1-py3-none-any.whl Python 3 none any Details for mcp_ssh_wrapper-0.1.1-py3-none-any.whl

Total release size: 57.5 kB

Release files / mcp_ssh_wrapper-0.1.1.tar.gz

Download URL mcp_ssh_wrapper-0.1.1.tar.gz
Size 50.7 kB
Tags Source
SHA-256 checksum
How to use checksums
4e35f75eeda161b7099c531e9674b4305085b15ad2532ac9f47d08da35ab80ba
BLAKE2b-256 checksum
How to use checksums
80273e63b59deec1c3517cebf74dd79b982f32b3b561e4b7e0ee00d4ac880f93
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Mar 15, 2026.

Transparency log

Release files / mcp_ssh_wrapper-0.1.1-py3-none-any.whl

Download URL mcp_ssh_wrapper-0.1.1-py3-none-any.whl
Size 6.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
281ffb7314a87f99e8f5fe10d16ec8d4c762075d0d0b390460c6095b4af40c08
BLAKE2b-256 checksum
How to use checksums
f60207f08b6ee7ae2d0c62de07abb4d6114847e80a062445d82a8af67f763fad
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Mar 15, 2026.

Transparency log

Security for mcp-ssh-wrapper 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for mcp_ssh_wrapper-0.1.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Mar 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page