SSH MCP

1# SSH MCP
2SSH MCP is an MCP server that runs locally on your host that provides the ability to manage and interact with remote SSH hosts. It supports organizing hosts into groups and executing commands across multiple hosts simultaneously.
3 
4## Tools
5 
6### Host Management
7- **add_host** - Adds a new Linux or Windows host to the SSH configuration with automatic OS detection. Username and password are optional in the connection string - if not provided, the current user and SSH agent will be used for authentication.
8- **remove_host** - Removes a host from the SSH configuration by group and name.
9- **get_groups** - Retrieves the list of all groups from the SSH configuration.
10- **get_hosts** - Retrieves the list of hosts from the SSH configuration. Can optionally filter by group.
11- **get_os_info** - Retrieves the cached operating system information for Linux and Windows hosts. You can specify individual hosts or an entire group.
12- **update_os_info** - Updates the cached operating system information for Linux and Windows hosts. You can specify individual hosts or an entire group.
13 
14### Command Execution
15- **perform_command** - SSH into a remote machine and executes a command. You can specify individual hosts or an entire group. Commands that take longer than 30 seconds are automatically moved to background execution. Use background=true to run immediately in background.
16 
17### Command Management
18- **get_command_status** - Retrieves the status and results of a background command by its command ID. If no ID is provided, returns the most recent command.
19- **list_commands** - Lists all background commands with their current status. Useful for tracking long-running commands.
20- **cancel_command** - Cancels a running background command by its command ID.
21 
22## Features
23 
24- **Cross-platform support** - Works with both Linux and Windows remote hosts with automatic OS detection
25- **Group-based organization** - Organize hosts into groups for easier management
26- **Multiple authentication methods** - Supports password, SSH agent, and SSH key files (~/.ssh/id_rsa, id_ed25519, etc.)
27- **Secure host verification** - Uses ~/.ssh/known_hosts for host key verification with automatic host addition
28- **Concurrent execution** - Execute commands across multiple hosts simultaneously
29- **Automatic background execution** - Commands that take longer than 30 seconds are automatically moved to background, with command IDs returned for status tracking
30- **Persistent storage** - Uses BadgerDB for efficient local storage
31 
32## Limitations
33 
34- SSH agent support is Unix-only (SSH_AUTH_SOCK) - password and key file authentication work on all platforms
35- Remote hosts can be Linux or Windows (automatic OS detection)
36 
37 
38## How to Setup
39 
40Checkout the repository:
41 
42```shell
43$ git clone https://github.com/blakerouse/ssh-mcp
44```
45 
46Build the binary:
47 
48```shell
49$ go build .
50```
51 
52Update the MCP configuration for Claude Desktop:
53 
54```
55{
56  "mcpServers": {
57    "ssh": {
58      "command": "<PATH_TO_BUILT_BINARY>"
59    }
60  }
61}
62```
63 
64Restart Claude Desktop
65 
66## How to Use
67 
68### Adding Hosts
69 
70Add a host to a group (multiple formats supported - `ssh://` prefix is optional):
71 
72```
73add host to production group connecting with 10.0.1.5
74add host named web01 to production group connecting with user@10.0.1.5:2222
75add host to staging group connecting with user:pass@10.0.1.10
76```
77 
78### Listing Groups and Hosts
79 
80List all groups:
81```
82show me all groups
83```
84 
85List all hosts:
86```
87list all my hosts
88```
89 
90List hosts in a specific group:
91```
92show me hosts in production group
93```
94 
95### Getting OS Information
96 
97Get OS info for all hosts in a group:
98```
99show OS information for production group
100```
101 
102Get OS info for specific hosts:
103```
104show OS information for production:web01 and production:web02
105```
106 
107### Executing Commands
108 
109Run a command on all hosts in a group:
110```
111run "uptime" on production group
112check disk space on staging group
113```
114 
115Run a command on specific hosts:
116```
117run "systemctl status nginx" on production:web01 and production:web02
118```
119 
120Commands that complete within 30 seconds will return results immediately. Longer commands are automatically moved to background:
121```
122run "apt-get update && apt-get upgrade -y" on production group
123# If this takes >30s, you'll get a command ID to check later
124```
125 
126Force a command to run in background immediately:
127```
128run "apt-get update && apt-get upgrade -y" on production group in the background
129```
130 
131### Managing Background Commands
132 
133Check the status of a background command:
134```
135show me the status of command abc-123-def
136show me the status of the last command
137```
138 
139List all background commands:
140```
141list all background commands
142show me all running commands
143```
144 
145Cancel a running command:
146```
147cancel command abc-123-def
148stop the running command abc-123-def
149```
150 
151### Updating OS Information
152 
153Update cached OS information:
154```
155update OS information for production group
156refresh OS info for staging:db01
157```
158 
159### Managing Hosts
160 
161Remove a host:
162```
163remove production:web01
164remove host web02 from staging group
165```
166