# SSH MCP Server

A Model Context Protocol (MCP) server that exposes SSH, SFTP, and tunnel capabilities as AI tools. Connect any MCP-compatible AI app to your remote servers.

## Tools (17 total)

| Category | Tools |
|----------|-------|
| **Connections** | `ssh_connect`, `ssh_disconnect`, `ssh_list_connections` |
| **Profiles** | `ssh_save_profile`, `ssh_list_profiles`, `ssh_delete_profile` |
| **Exec** | `ssh_exec` |
| **SFTP** | `sftp_upload`, `sftp_download`, `sftp_list`, `sftp_stat`, `sftp_mkdir`, `sftp_rm` |
| **Tunnels** | `ssh_forward_local`, `ssh_forward_remote`, `ssh_list_tunnels`, `ssh_close_tunnel` |

---

## Prerequisites

- [Node.js](https://nodejs.org/) v18+
- Clone and build the server:

```bash
git clone <your-repo-url>
cd ssh-mcp
npm install
npm run build
```

The built entry point will be at `dist/index.js`.

---

## Connecting to AI Apps

> **Replace** `/path/to/ssh-mcp` with the actual absolute path where you cloned the repo.
>
> - **Windows example:** `D:/projects/ssh-mcp`
> - **macOS/Linux example:** `/home/user/ssh-mcp`

---

### Claude Desktop

**Config file location:**
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

Open the file and add the `mcpServers` block (merge with existing content if needed):

```json
{
  "mcpServers": {
    "ssh": {
      "command": "node",
      "args": ["/path/to/ssh-mcp/dist/index.js"]
    }
  }
}
```

**Windows example:**
```json
{
  "mcpServers": {
    "ssh": {
      "command": "node",
      "args": ["D:/projects/ssh-mcp/dist/index.js"]
    }
  }
}
```

**Steps:**
1. Edit the config file above
2. Fully quit Claude Desktop (right-click tray icon → Quit)
3. Relaunch Claude Desktop
4. Look for the 🔨 hammer icon in the chat input — click it to verify SSH tools are listed

---

### Google Antigravity

**Config file location:**
- Windows: `C:\Users\<YOUR_USERNAME>\.gemini\antigravity\mcp_config.json`
- macOS/Linux: `~/.gemini/antigravity/mcp_config.json`

Create or edit `mcp_config.json`:

```json
{
  "mcpServers": {
    "ssh": {
      "command": "node",
      "args": ["/path/to/ssh-mcp/dist/index.js"]
    }
  }
}
```

**Alternatively via the UI:**
1. Open Antigravity → click **Agent** session dropdown in the side panel
2. Select **MCP Servers** → **Manage MCP Servers**
3. Click **View raw config** and paste the config above

**Steps:**
1. Save the config file
2. Restart Antigravity or reload the MCP servers from the UI
3. The SSH tools will appear in the agent tool list

---

### VS Code (GitHub Copilot Chat)

MCP servers in VS Code can be scoped to a **workspace** or configured **globally**.

#### Option A — Workspace (recommended)

Create `.vscode/mcp.json` in your project root:

```json
{
  "servers": {
    "ssh": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/ssh-mcp/dist/index.js"]
    }
  }
}
```

#### Option B — Global (user settings)

Open VS Code settings (`Ctrl+,` / `Cmd+,`) → search for **MCP** → click **Edit in settings.json** and add:

```json
{
  "mcp": {
    "servers": {
      "ssh": {
        "type": "stdio",
        "command": "node",
        "args": ["/path/to/ssh-mcp/dist/index.js"]
      }
    }
  }
}
```

**Steps:**
1. Save the config
2. Open Copilot Chat (`Ctrl+Alt+I` / `Cmd+Alt+I`)
3. Switch to **Agent** mode using the mode selector
4. The SSH tools will be available to the agent

> **Requires:** VS Code 1.99+ with the GitHub Copilot extension

---

### Opencode

**Config file location:** `~/.config/opencode/config.json`

Add the `mcp` block to your config (create the file if it doesn't exist):

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "ssh": {
      "type": "local",
      "command": ["node", "/path/to/ssh-mcp/dist/index.js"],
      "enabled": true
    }
  }
}
```

**Steps:**
1. Save the config file
2. Start or restart `opencode`
3. The SSH tools will be loaded automatically on startup

> The `command` field in Opencode is an **array** (command + args combined), unlike other apps that split them into `command` + `args`.

### LM Studio

LM Studio supports MCP servers since version **0.3.17**. It uses the same `mcpServers` format as Claude Desktop.

**Config file via UI (easiest):**
1. Open LM Studio → switch to the **Program** tab in the right sidebar
2. Click **Install** → **Edit mcp.json** — this opens the config in the built-in editor
3. Add the SSH server entry and save

**mcp.json format:**

```json
{
  "mcpServers": {
    "ssh": {
      "command": "node",
      "args": ["/path/to/ssh-mcp/dist/index.js"]
    }
  }
}
```

**Windows example:**
```json
{
  "mcpServers": {
    "ssh": {
      "command": "node",
      "args": ["D:/projects/ssh-mcp/dist/index.js"]
    }
  }
}
```

**Steps:**
1. Edit `mcp.json` via the UI or directly on disk
2. Save the file — LM Studio reloads MCP servers automatically
3. Load a model that supports tool use (e.g. a Qwen, Llama, or Mistral instruct model)
4. Start a new chat — LM Studio will show a confirmation dialog before executing any tool call

> **Note:** LM Studio shows a tool-call confirmation dialog before running each tool, letting you review and optionally edit the arguments first.
>
> **Requires:** LM Studio 0.3.17+

---

## Authentication Methods

When connecting with `ssh_connect`, three auth methods are supported:

| Method | When to use |
|--------|-------------|
| `password` | Username + password login |
| `key` | Private key file (PEM format) |
| `agent` | SSH agent (e.g. `ssh-agent`, Pageant on Windows) |

**Password example:**
```
ssh_connect host=192.168.1.10 username=admin auth=password password=secret
```

**Key example:**
```
ssh_connect host=192.168.1.10 username=admin auth=key privateKeyPath=/home/user/.ssh/id_rsa
```

**Agent example:**
```
ssh_connect host=192.168.1.10 username=admin auth=agent
```

### Saving profiles

To avoid re-entering credentials every session, save a profile:
```
ssh_save_profile name=myserver host=192.168.1.10 username=admin auth=password
```

Then connect using:
```
ssh_connect profileName=myserver password=secret
```

---

## Development

```bash
# Run without building (uses tsx)
npm run dev

# Build to dist/
npm run build

# Type-check only
npm run typecheck
```

---

## Troubleshooting

| Problem | Fix |
|---------|-----|
| Tools don't appear in the app | Make sure you ran `npm run build` and `dist/index.js` exists |
| `Cannot find module` error | Run `npm install` then `npm run build` again |
| Connection refused | Check the host/port and that the SSH service is running on the remote |
| Auth failed | Double-check username, password, or key path and permissions |
| Antigravity doesn't load tools | Reload MCP servers from the UI or restart Antigravity |
| VS Code tools missing | Ensure you're in **Agent** mode in Copilot Chat, not Ask/Edit mode |
| LM Studio tools missing | Requires v0.3.17+; make sure you're using a model that supports tool use |