SSH远程命令服务器

mcp-ssh-server

English | 简体中文

MCP server that runs remote commands over SSH using allowlists and session approvals.

Install (runtime)

• Create venv and install deps:
  • pip install mcp asyncssh

Configure

• Keep real credentials outside LLM-readable project workspaces.
• Recommended: copy ssh_profiles.example.json to a private path and pass it with MCP_SSH_CONFIG from your MCP client config:

{
  "command": "D:\\Other\\mcp\\mcp-ssh-server\\mcp-ssh-server.exe",
  "env": {
    "MCP_SSH_CONFIG": "D:\\Other\\mcp\\mcp-ssh-server\\ssh_profiles.json"
  },
  "type": "stdio"
}

• If MCP_SSH_CONFIG is set, that path is always used.
• If MCP_SSH_CONFIG is not set, a packaged binary also checks for ssh_profiles.json next to the executable.
• If neither of the above is available, the fallback user config paths are:
  • Windows: %APPDATA%\mcp-ssh-server\ssh_profiles.json
  • macOS: ~/Library/Application Support/mcp-ssh-server/ssh_profiles.json
  • Linux: $XDG_CONFIG_HOME/mcp-ssh-server/ssh_profiles.json or ~/.config/mcp-ssh-server/ssh_profiles.json
• Set SSH key path/password env vars referenced by your profile.

For source-tree development, the default lookup intentionally does not read ./ssh_profiles.json.

Run (stdio)

• python mcp_ssh_server.py

Package to a single file (PyInstaller)

• pip install pyinstaller
• pyinstaller -F --name mcp-ssh-server mcp_ssh_server.py
• Output binary is in dist/

Package via GitHub Actions

• Go to Actions -> Package -> Run workflow
• Download artifact: mcp-ssh-server-
• The zip contains:
  • mcp-ssh-server(.exe)
  • ssh_profiles.json (default allowlist)

Use the packaged zip

• Unzip the artifact
• Edit ssh_profiles.json (set host/username/auth)
• Run:
  • Windows: .\mcp-ssh-server.exe
  • Linux/macOS: ./mcp-ssh-server
• Optionally set MCP_SSH_CONFIG to point to another path

Tools

• ssh_list_profiles: list configured profiles
• ssh_run_command: run an allowlisted command by profile
• ssh_approve_and_run: approve a pending command and run it
• ssh_clear_session_allowlist: clear session prefixes

Approval flow

1. Call ssh_run_command
2. If the command is not in the JSON allowlist, the tool returns approval_required with:
   • approval_id
   • choices: allow_once or allow_prefix
   • suggested_prefix (e.g., "git pull" instead of "git")
3. Ask the user, then call ssh_approve_and_run with approval_id and decision

Session prefixes are stored in memory and cleared when the server process exits or when you call ssh_clear_session_allowlist. Commands containing shell control operators such as ;, &&, |, redirects, command substitution, or backgrounding are rejected by default. Set allow_shell_operators only for trusted profiles that intentionally need shell composition.

License

Apache-2.0. See LICENSE.