Archived
gitea-actions[bot]
263 lines
7.0 KiB
Markdown
263 lines
7.0 KiB
Markdown
← [Home](Home)
|
|
|
|
# Installation Guide
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
| Requirement | Minimum Version | Notes |
|
|
|-------------|-----------------|-------|
|
|
| Node.js | 18.0.0 | LTS recommended |
|
|
| npm | 9.x | Ships with Node.js 18+ |
|
|
| SSH key pair | -- | Ed25519 recommended (`ssh-keygen -t ed25519`) |
|
|
| rsync | -- | Required only for `ssh_sync` |
|
|
| sshpass | -- | Required only for `ssh_sync` with password auth |
|
|
|
|
### Generating an SSH Key
|
|
|
|
If you do not already have an SSH key:
|
|
|
|
```bash
|
|
ssh-keygen -t ed25519 -C "your_email@example.com"
|
|
```
|
|
|
|
Copy the public key to each remote server:
|
|
|
|
```bash
|
|
ssh-copy-id -i ~/.ssh/id_ed25519.pub user@host
|
|
```
|
|
|
|
---
|
|
|
|
## Install
|
|
|
|
Clone the repository and install dependencies:
|
|
|
|
```bash
|
|
git clone https://git.mokoconsulting.tech/MokoConsulting/ssh-mcp.git
|
|
cd ssh-mcp
|
|
npm install
|
|
```
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
ssh-mcp reads server definitions from environment variables. The recommended approach is a `.env` file stored at `~/.ssh-manager/.env`.
|
|
|
|
### .env File Search Order
|
|
|
|
The server searches for `.env` in this order:
|
|
|
|
| Priority | Location | Description |
|
|
|----------|----------|-------------|
|
|
| 1 | `SSH_ENV_PATH` environment variable | Explicit override |
|
|
| 2 | `~/.ssh-manager/.env` | User config directory |
|
|
| 3 | `<cwd>/.env` | Current working directory |
|
|
| 4 | `~/.env` | Home directory |
|
|
| 5 | `<install-dir>/.env` | Backward compatibility |
|
|
|
|
### .env Format
|
|
|
|
Each server is defined by a set of variables sharing a common name prefix. The name is case-insensitive and is used to reference the server in tool calls.
|
|
|
|
```dotenv
|
|
# --- Required ---
|
|
SSH_SERVER_PRODUCTION_HOST=192.168.1.100
|
|
SSH_SERVER_PRODUCTION_USER=deploy
|
|
|
|
# --- Authentication (pick one) ---
|
|
SSH_SERVER_PRODUCTION_KEYPATH=~/.ssh/id_ed25519
|
|
# or
|
|
SSH_SERVER_PRODUCTION_PASSWORD=s3cret
|
|
|
|
# --- Optional ---
|
|
SSH_SERVER_PRODUCTION_PASSPHRASE=key_passphrase
|
|
SSH_SERVER_PRODUCTION_PORT=22
|
|
SSH_SERVER_PRODUCTION_DEFAULT_DIR=/var/www/myapp
|
|
SSH_SERVER_PRODUCTION_SUDO_PASSWORD=sudopass
|
|
SSH_SERVER_PRODUCTION_PLATFORM=linux # "linux" (default) or "windows"
|
|
SSH_SERVER_PRODUCTION_PROXYJUMP=bastion # Name of another configured server
|
|
SSH_SERVER_PRODUCTION_PROXYCOMMAND=ncat --proxy 127.0.0.1:1080 --proxy-type socks5 %h %p
|
|
```
|
|
|
|
### Field Reference
|
|
|
|
| Field | Required | Description |
|
|
|-------|----------|-------------|
|
|
| `HOST` | Yes | Hostname or IP address |
|
|
| `USER` | Yes | SSH username |
|
|
| `PASSWORD` | Auth | Password for password-based authentication |
|
|
| `KEYPATH` | Auth | Path to SSH private key file |
|
|
| `PASSPHRASE` | No | Passphrase for encrypted private keys |
|
|
| `PORT` | No | SSH port (default: 22) |
|
|
| `DEFAULT_DIR` | No | Default working directory for commands |
|
|
| `SUDO_PASSWORD` | No | Password for sudo operations |
|
|
| `PLATFORM` | No | `linux` (default) or `windows` |
|
|
| `PROXYJUMP` | No | Name of a configured server to use as a jump host |
|
|
| `PROXYCOMMAND` | No | Custom proxy command (supports `%h` and `%p` placeholders) |
|
|
|
|
### TOML Format (Alternative)
|
|
|
|
ssh-mcp also supports TOML configuration, useful for OpenAI Codex integration. Place the file at `~/.codex/ssh-config.toml` or set `SSH_CONFIG_PATH`:
|
|
|
|
```toml
|
|
[ssh_servers.production]
|
|
host = "192.168.1.100"
|
|
user = "deploy"
|
|
key_path = "~/.ssh/id_ed25519"
|
|
port = 22
|
|
default_dir = "/var/www/myapp"
|
|
```
|
|
|
|
Set `PREFER_TOML_CONFIG=true` to prefer TOML over `.env` when both exist.
|
|
|
|
---
|
|
|
|
## Claude Code Registration
|
|
|
|
Register the MCP server with Claude Code:
|
|
|
|
```bash
|
|
claude mcp add ssh-manager node /absolute/path/to/ssh-mcp/src/index.js
|
|
```
|
|
|
|
The configuration is stored in `~/.config/claude-code/claude_code_config.json`.
|
|
|
|
After registration, Claude Code will list the ssh-mcp tools automatically. You can verify by asking Claude Code to run `ssh_list_servers`.
|
|
|
|
---
|
|
|
|
## Multiple Server Setup
|
|
|
|
Define as many servers as you need by repeating the variable block with different names:
|
|
|
|
```dotenv
|
|
# Production
|
|
SSH_SERVER_PRODUCTION_HOST=prod.example.com
|
|
SSH_SERVER_PRODUCTION_USER=deploy
|
|
SSH_SERVER_PRODUCTION_KEYPATH=~/.ssh/id_ed25519
|
|
|
|
# Staging
|
|
SSH_SERVER_STAGING_HOST=staging.example.com
|
|
SSH_SERVER_STAGING_USER=deploy
|
|
SSH_SERVER_STAGING_KEYPATH=~/.ssh/id_ed25519
|
|
|
|
# Database server
|
|
SSH_SERVER_DB_HOST=db.internal
|
|
SSH_SERVER_DB_USER=dba
|
|
SSH_SERVER_DB_KEYPATH=~/.ssh/id_ed25519
|
|
SSH_SERVER_DB_DEFAULT_DIR=/var/lib/mysql
|
|
|
|
# Bastion / jump host
|
|
SSH_SERVER_BASTION_HOST=bastion.example.com
|
|
SSH_SERVER_BASTION_USER=admin
|
|
SSH_SERVER_BASTION_KEYPATH=~/.ssh/id_ed25519
|
|
|
|
# Server behind bastion
|
|
SSH_SERVER_INTERNAL_HOST=10.0.0.5
|
|
SSH_SERVER_INTERNAL_USER=deploy
|
|
SSH_SERVER_INTERNAL_KEYPATH=~/.ssh/id_ed25519
|
|
SSH_SERVER_INTERNAL_PROXYJUMP=bastion
|
|
```
|
|
|
|
### Server Groups
|
|
|
|
After defining servers, you can organize them into groups using the `ssh_group_manage` tool:
|
|
|
|
```
|
|
ssh_group_manage action=create name=web-servers servers=["production","staging"]
|
|
```
|
|
|
|
Then execute commands across the group:
|
|
|
|
```
|
|
ssh_execute_group group=web-servers command="uptime"
|
|
```
|
|
|
|
---
|
|
|
|
## Tool Management
|
|
|
|
By default all 37 tools are enabled. To reduce context usage in Claude Code, use the CLI to disable groups you do not need:
|
|
|
|
```bash
|
|
ssh-manager tools configure # Interactive wizard
|
|
ssh-manager tools disable monitoring
|
|
ssh-manager tools disable database
|
|
ssh-manager tools list # Verify
|
|
```
|
|
|
|
See [Tool Management](TOOL_MANAGEMENT) for details.
|
|
|
|
---
|
|
|
|
## Development Setup
|
|
|
|
Install pre-commit hooks for secret scanning:
|
|
|
|
```bash
|
|
./scripts/setup-hooks.sh
|
|
```
|
|
|
|
Run tests:
|
|
|
|
```bash
|
|
npm test
|
|
```
|
|
|
|
Run the validation suite:
|
|
|
|
```bash
|
|
./scripts/validate.sh
|
|
```
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### "Server not found" errors
|
|
|
|
- Server names are case-insensitive. `PRODUCTION`, `production`, and `Production` all resolve to the same entry.
|
|
- Verify the `.env` file is in one of the searched locations (see table above).
|
|
- Run `ssh_list_servers` to see which servers are loaded.
|
|
|
|
### Connection timeouts
|
|
|
|
- Check that the remote host is reachable: `ssh -v user@host`
|
|
- Ensure port 22 (or your custom port) is open in firewalls.
|
|
- Idle connections are closed after 30 minutes. The server will reconnect automatically on the next tool call.
|
|
|
|
### Permission denied (publickey)
|
|
|
|
- Confirm the key path in `KEYPATH` points to the correct private key.
|
|
- Verify the public key is in `~/.ssh/authorized_keys` on the remote server.
|
|
- Check key file permissions: `chmod 600 ~/.ssh/id_ed25519`
|
|
|
|
### rsync / ssh_sync failures
|
|
|
|
- `ssh_sync` requires `rsync` installed on both local and remote machines.
|
|
- Password-based auth additionally requires `sshpass` on the local machine.
|
|
|
|
### Host key verification failed
|
|
|
|
- Use `ssh_key_manage action=verify server=name` to inspect the key.
|
|
- If the server was reinstalled, use `ssh_key_manage action=accept server=name` to trust the new key.
|
|
|
|
### Logs
|
|
|
|
Set `SSH_LOG_LEVEL=DEBUG` in your environment for verbose logging. Logs are written to stderr.
|
|
|
|
```bash
|
|
SSH_LOG_LEVEL=DEBUG node src/index.js 2>debug.log
|
|
```
|
|
|
|
---
|
|
|
|
*Repo: [ssh-mcp](https://git.mokoconsulting.tech/MokoConsulting/ssh-mcp) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)*
|
|
|
|
| Revision | Date | Author | Description |
|
|
|---|---|---|---|
|
|
| 1.0 | 2026-05-09 | Moko Consulting | Initial version |
|