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
sshcommand directly - Returns
stdout,stderr, andexit_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 oruser@host, resolved by the local SSH clientcommand: Command string to execute remotelytimeout_seconds: Optional timeout.0disables timeout handling.
Result:
{
"host": "prod-box",
"command": "uname -a",
"stdout": "Linux ...\n",
"stderr": "",
"exit_code": 0
}
Notes
- SSH options should be configured in
~/.ssh/configor 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
sshclient 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:
- Update
project.versionin pyproject.toml. - Commit the version bump and push it to
main. - Tag the
maincommit with a matching version tag in the formvX.Y.Z. - 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
pypienvironment
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.