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 v18+
• Clone and build the server:

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):

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

Windows example:

{
  "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:

{
  "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:

{
  "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:

{
  "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):

{
  "$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:

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

Windows example:

{
  "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

# 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