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