mcp-ssh-wrapper 0.1.1__tar.gz

mcp_ssh_wrapper-0.1.1/.github/workflows/publish-pypi.yml

@@ -0,0 +1,71 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Ensure tag points to main
+        run: |
+          git fetch origin main --depth=1
+          git merge-base --is-ancestor "$GITHUB_SHA" "origin/main"
+
+      - name: Derive version from tag
+        id: version
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Verify tag matches package version
+        run: |
+          package_version="$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")"
+          test "$package_version" = "${{ steps.version.outputs.version }}"
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

mcp_ssh_wrapper-0.1.1/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.coverage
+build/
+dist/
+*.egg-info/
+.venv

mcp_ssh_wrapper-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Megascope
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_ssh_wrapper-0.1.1/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: mcp-ssh-wrapper
+Version: 0.1.1
+Summary: An MCP server that executes remote commands through the host ssh binary.
+Author: megascope
+License: MIT
+License-File: LICENSE
+Keywords: mcp,server,ssh
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0.0
+Description-Content-Type: text/markdown
+
+# 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
+
+```bash
+pip install mcp-ssh-wrapper
+```
+
+## Running the server
+
+After installation, run the server with:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+./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:
+
+```bash
+mcp-ssh-wrapper --host 127.0.0.1 --port 8000 --mount-path /mcp
+```
+
+Then register the running HTTP endpoint with Codex:
+
+```bash
+codex mcp add mcp-ssh --url http://127.0.0.1:8000/mcp
+```
+
+Verify the registration:
+
+```bash
+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:
+
+```bash
+claude mcp add mcp-ssh --transport http http://127.0.0.1:8000/mcp
+```
+
+Verify the registration:
+
+```bash
+claude mcp list
+claude mcp get mcp-ssh
+```
+
+### Claude Desktop
+
+Add this server entry to your `claude_desktop_config.json`:
+
+```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:
+
+```bash
+./run_test.sh --skip-call
+```
+
+To target a non-default endpoint:
+
+```bash
+./run_test.sh --url http://127.0.0.1:8000/mcp --skip-call
+```
+
+To also invoke the SSH tool:
+
+```bash
+./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:
+
+```json
+{
+  "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](mcp-ssh-wrapper/.github/workflows/publish-pypi.yml).
+
+Release flow:
+
+1. Update `project.version` in [pyproject.toml](mcp-ssh-wrapper/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`:
+
+```bash
+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

mcp_ssh_wrapper-0.1.1/README.md

@@ -0,0 +1,187 @@
+# 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
+
+```bash
+pip install mcp-ssh-wrapper
+```
+
+## Running the server
+
+After installation, run the server with:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+./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:
+
+```bash
+mcp-ssh-wrapper --host 127.0.0.1 --port 8000 --mount-path /mcp
+```
+
+Then register the running HTTP endpoint with Codex:
+
+```bash
+codex mcp add mcp-ssh --url http://127.0.0.1:8000/mcp
+```
+
+Verify the registration:
+
+```bash
+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:
+
+```bash
+claude mcp add mcp-ssh --transport http http://127.0.0.1:8000/mcp
+```
+
+Verify the registration:
+
+```bash
+claude mcp list
+claude mcp get mcp-ssh
+```
+
+### Claude Desktop
+
+Add this server entry to your `claude_desktop_config.json`:
+
+```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:
+
+```bash
+./run_test.sh --skip-call
+```
+
+To target a non-default endpoint:
+
+```bash
+./run_test.sh --url http://127.0.0.1:8000/mcp --skip-call
+```
+
+To also invoke the SSH tool:
+
+```bash
+./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:
+
+```json
+{
+  "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](mcp-ssh-wrapper/.github/workflows/publish-pypi.yml).
+
+Release flow:
+
+1. Update `project.version` in [pyproject.toml](mcp-ssh-wrapper/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`:
+
+```bash
+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

mcp_ssh_wrapper-0.1.1/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling>=1.27.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mcp-ssh-wrapper"
+version = "0.1.1"
+description = "An MCP server that executes remote commands through the host ssh binary."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+  { name = "megascope" }
+]
+keywords = ["mcp", "ssh", "server"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Internet",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "mcp>=1.0.0",
+]
+
+[project.scripts]
+mcp-ssh-wrapper = "mcp_ssh_wrapper.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_ssh_wrapper"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

mcp_ssh_wrapper-0.1.1/run_server.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "$0")" && pwd)"
+cd "$repo_root"
+
+# If started outside an interactive shell, recover the macOS ssh-agent socket.
+if [[ -z "${SSH_AUTH_SOCK:-}" ]] && command -v launchctl >/dev/null 2>&1; then
+  ssh_auth_sock="$(launchctl getenv SSH_AUTH_SOCK 2>/dev/null || true)"
+  if [[ -n "$ssh_auth_sock" ]]; then
+    export SSH_AUTH_SOCK="$ssh_auth_sock"
+  fi
+fi
+
+exec uv run --python 3.10 --with mcp mcp-ssh-wrapper "$@"

mcp_ssh_wrapper-0.1.1/run_test.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "$0")" && pwd)"
+cd "$repo_root"
+
+exec uv run --python 3.10 --with mcp python scripts/test_http_client.py "$@"

mcp_ssh_wrapper-0.1.1/scripts/test_http_client.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+from typing import Any
+
+from mcp import ClientSession
+from mcp.client.streamable_http import streamablehttp_client
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Smoke-test a running mcp-ssh-wrapper over streamable HTTP."
+    )
+    parser.add_argument(
+        "--url",
+        default="http://127.0.0.1:8000/mcp",
+        help="MCP streamable HTTP endpoint. Defaults to http://127.0.0.1:8000/mcp.",
+    )
+    parser.add_argument("--host", help="Remote SSH host to target for execute_command.")
+    parser.add_argument("--command", help="Remote command to execute.")
+    parser.add_argument(
+        "--skip-call",
+        action="store_true",
+        help="Only initialize the server and list tools.",
+    )
+    parser.add_argument(
+        "--timeout-seconds",
+        type=int,
+        default=0,
+        help="Timeout forwarded to execute_command.",
+    )
+    return parser.parse_args()
+
+
+def to_jsonable(value: Any) -> Any:
+    if hasattr(value, "model_dump"):
+        return value.model_dump(mode="json")
+    if isinstance(value, list):
+        return [to_jsonable(item) for item in value]
+    if isinstance(value, dict):
+        return {key: to_jsonable(item) for key, item in value.items()}
+    return value
+
+
+def dump_message(title: str, message: Any) -> None:
+    print(f"== {title} ==")
+    print(json.dumps(to_jsonable(message), indent=2, sort_keys=True))
+
+
+async def run() -> int:
+    args = parse_args()
+
+    async with streamablehttp_client(args.url) as (read_stream, write_stream, _):
+        async with ClientSession(read_stream, write_stream) as session:
+            initialize = await session.initialize()
+            dump_message("initialize", initialize)
+
+            tools = await session.list_tools()
+            dump_message("tools/list", tools)
+
+            if not args.skip_call:
+                if not args.host or not args.command:
+                    raise SystemExit("--host and --command are required unless --skip-call is used")
+
+                call = await session.call_tool(
+                    "execute_command",
+                    {
+                        "host": args.host,
+                        "command": args.command,
+                        "timeout_seconds": args.timeout_seconds,
+                    },
+                )
+                dump_message("tools/call", call)
+
+    return 0
+
+
+def main() -> int:
+    return asyncio.run(run())
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mcp_ssh_wrapper-0.1.1/src/mcp_ssh_wrapper/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

mcp_ssh_wrapper-0.1.1/src/mcp_ssh_wrapper/__main__.py

@@ -0,0 +1,5 @@
+from mcp_ssh_wrapper.server import main
+
+
+if __name__ == "__main__":
+    main()