{"id":47998875,"url":"https://github.com/blackaxgit/ssh-mcp","last_synced_at":"2026-04-04T12:10:34.685Z","repository":{"id":341954057,"uuid":"1156537624","full_name":"blackaxgit/ssh-mcp","owner":"blackaxgit","description":"MCP server that gives AI assistants (Claude) SSH access to run commands, transfer files, and manage server fleets","archived":false,"fork":false,"pushed_at":"2026-03-04T03:11:33.000Z","size":86,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-04T07:39:17.307Z","etag":null,"topics":["ai","automation","claude","devops","infrastructure","mcp","model-context-protocol","python","ssh"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blackaxgit.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-12T19:02:49.000Z","updated_at":"2026-03-04T03:11:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/blackaxgit/ssh-mcp","commit_stats":null,"previous_names":["blackaxgit/ssh-mcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/blackaxgit/ssh-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackaxgit%2Fssh-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackaxgit%2Fssh-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackaxgit%2Fssh-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackaxgit%2Fssh-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blackaxgit","download_url":"https://codeload.github.com/blackaxgit/ssh-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackaxgit%2Fssh-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31398892,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","automation","claude","devops","infrastructure","mcp","model-context-protocol","python","ssh"],"created_at":"2026-04-04T12:10:34.092Z","updated_at":"2026-04-04T12:10:34.677Z","avatar_url":"https://github.com/blackaxgit.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ssh-mcp\n\nSSH MCP server that lets AI assistants execute commands on remote servers.\n\n[![License: MPL-2.0](https://img.shields.io/badge/License-MPL--2.0-brightgreen.svg)](LICENSE)\n[![Claude Code Ready](https://img.shields.io/badge/Claude_Code-Auto_Install_Ready-blueviolet?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiIgdmlld0JveD0iMCAwIDE2IDE2Ij48dGV4dCB4PSIwIiB5PSIxMyIgZm9udC1zaXplPSIxNCI+8J+UpTwvdGV4dD48L3N2Zz4=)](#add-to-claude-code)\n\n## What is this\n\nssh-mcp is a [Model Context Protocol](https://modelcontextprotocol.io/) server that gives AI assistants like Claude direct access to your SSH infrastructure. Once configured, Claude can run commands, transfer files, and query server groups across your fleet without leaving the conversation.\n\nConnection details are read from your existing `~/.ssh/config`. No credentials are stored in the MCP configuration.\n\n## Features\n\n- Run shell commands on individual servers or across entire groups in parallel\n- SFTP file upload and download over the existing SSH session\n- Connection pooling — reuses SSH connections across tool calls\n- Dangerous command detection — warns before executing destructive operations\n- Server groups for organizing hosts (production, staging, per-service)\n- SSH config integration — reads host, port, user, and identity from `~/.ssh/config`\n- Custom config path via `SSH_MCP_CONFIG` environment variable\n\n## Quick Start\n\n### Install\n\n```bash\n# Run directly with uvx (no install required)\nuvx ssh-mcp\n\n# Or install with pip\npip install ssh-mcp\n```\n\nRequires Python 3.11+. Install [uv](https://docs.astral.sh/uv/getting-started/installation/) to use `uvx`.\n\n### Create a config file\n\n```bash\nmkdir -p ~/.config/ssh-mcp\ncp config/servers.example.toml ~/.config/ssh-mcp/servers.toml\n```\n\nEdit `~/.config/ssh-mcp/servers.toml` and add your servers. Server names must match `Host` entries in `~/.ssh/config`.\n\n### Add to Claude Desktop\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent on your platform:\n\n```json\n{\n  \"mcpServers\": {\n    \"ssh-mcp\": {\n      \"command\": \"uvx\",\n      \"args\": [\"ssh-mcp\"]\n    }\n  }\n}\n```\n\nTo use a non-default config path, pass the environment variable:\n\n```json\n{\n  \"mcpServers\": {\n    \"ssh-mcp\": {\n      \"command\": \"uvx\",\n      \"args\": [\"ssh-mcp\"],\n      \"env\": {\n        \"SSH_MCP_CONFIG\": \"/path/to/servers.toml\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop after editing the config.\n\n### Add to Claude Code\n\nIf you use [Claude Code](https://docs.anthropic.com/en/docs/claude-code) instead of Claude Desktop, you can set everything up from the terminal:\n\n```bash\n# 1. Add the MCP server\nclaude mcp add ssh-mcp -- uvx ssh-mcp\n\n# 2. Create the config directory and copy the example\nmkdir -p ~/.config/ssh-mcp\ncurl -sL https://raw.githubusercontent.com/blackaxgit/ssh-mcp/main/config/servers.example.toml \\\n  \u003e ~/.config/ssh-mcp/servers.toml\n\n# 3. Edit with your servers (server names must match ~/.ssh/config Host entries)\n${EDITOR:-nano} ~/.config/ssh-mcp/servers.toml\n\n# 4. Restrict permissions\nchmod 600 ~/.config/ssh-mcp/servers.toml\n```\n\nTo use a custom config path:\n\n```bash\nclaude mcp add ssh-mcp -e SSH_MCP_CONFIG=/path/to/servers.toml -- uvx ssh-mcp\n```\n\n## Configuration\n\nConfig file location (checked in order):\n\n1. `$SSH_MCP_CONFIG` environment variable\n2. `~/.config/ssh-mcp/servers.toml` (default)\n3. `config/servers.toml` relative to the package (development only)\n\nExample `servers.toml`:\n\n```toml\n[settings]\nssh_config_path = \"~/.ssh/config\"\ncommand_timeout = 30\nmax_output_bytes = 51200\nconnection_idle_timeout = 300\nknown_hosts = true\n\n[groups]\nproduction = { description = \"Production servers\" }\nstaging    = { description = \"Staging servers\" }\n\n[servers.web-prod-01]\ndescription = \"Production web server\"\ngroups      = [\"production\"]\n\n[servers.web-staging-01]\ndescription = \"Staging web server\"\ngroups      = [\"staging\"]\njump_host   = \"bastion\"\n\n[servers.db-prod-01]\ndescription = \"Production database\"\ngroups      = [\"production\"]\nuser        = \"dbadmin\"\n```\n\nPer-server overrides (`user`, `jump_host`) take precedence over `~/.ssh/config`. See [config/servers.example.toml](config/servers.example.toml) for the full reference.\n\nRestrict config file permissions to your user:\n\n```bash\nchmod 600 ~/.config/ssh-mcp/servers.toml\n```\n\n## Available Tools\n\n| Tool | Description |\n|------|-------------|\n| `list_servers` | List configured servers; optionally filter by group |\n| `list_groups` | List server groups with member counts |\n| `execute` | Run a shell command on a single server |\n| `execute_on_group` | Run a command on all servers in a group (parallel) |\n| `upload_file` | Upload a local file to a server via SFTP |\n| `download_file` | Download a file from a server via SFTP |\n\n## Security\n\nssh-mcp warns before running commands that match known destructive patterns (`rm -rf`, disk wipes, shutdown). These are informational warnings — the AI assistant can still proceed if the operator confirms. Hard blocking is not enforced by design; access control is the operator's responsibility via SSH permissions on the target host.\n\nHost key verification is on by default (`known_hosts = true`). Disabling `StrictHostKeyChecking` in `~/.ssh/config` weakens MITM protection and should be avoided in production.\n\nFor vulnerability reports, see [SECURITY.md](SECURITY.md). Do not open public GitHub issues for security concerns.\n\n## Development\n\n```bash\ngit clone https://github.com/blackaxgit/ssh-mcp.git\ncd ssh-mcp\nuv sync --extra dev\nuv run pytest\nuv run ruff check .\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on making changes and submitting pull requests.\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md).\n\n## License\n\nMozilla Public License 2.0. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblackaxgit%2Fssh-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblackaxgit%2Fssh-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblackaxgit%2Fssh-mcp/lists"}