# SSH MCP Server 🚀

Control your remote servers using **natural language** through Claude Desktop or Cursor IDE! This MCP (Model Context Protocol) server lets you talk to your AI assistant—"Connect to my server and show disk usage"—and it runs the SSH commands for you. No need to open a terminal or remember commands.

Perfect for **Linux VMs**, **Google Cloud**, **AWS EC2**, **DigitalOcean**, and any server you can reach via SSH.

### 🔌 What is MCP?

MCP (Model Context Protocol) lets AI apps like Claude and Cursor use external tools. This server adds **SSH** as a tool—so your AI can connect to servers and run commands when you ask.

---

## 🤖 Installation for AI Agents

**If you're an AI agent or someone setting this up via AI:** Use these instructions to install the SSH MCP server.

**If you're a user asking your AI to install this:** Copy and paste this to your AI:

> *"Install the SSH MCP server from https://github.com/mertcankaraoglu/ssh-mcp — add it to my MCP config and tell me when it's done. Follow the README instructions."*

1. **Prerequisites:** Node.js v18+ must be installed. ([Download](https://nodejs.org/))
2. **Config file:** Add the block below to the MCP config file:
   - **Claude Desktop:** `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
   - **Cursor IDE:** `~/.cursor/mcp.json` or `%USERPROFILE%\.cursor\mcp.json` (Windows)
3. **Add this JSON** inside `mcpServers`:

```json
"ssh": {
  "command": "npx",
  "args": ["-y", "git+https://github.com/mertcankaraoglu/ssh-mcp.git#main"]
}
```

4. **Restart** the application. The user can then ask you to connect to their server (with password or SSH key).

---

## 🎯 Why Use This?

Instead of opening PuTTY or typing `ssh user@server` in a terminal, you simply tell your AI:

> *"Connect to my Ubuntu server at 192.168.1.100 and run df -h"*

Your AI handles the connection and shows you the results. Great for developers, DevOps, or anyone who manages remote servers and wants a simpler workflow.

---

## ✨ Features

| Feature | Description |
|---------|-------------|
| 🔐 **Password or SSH key** | Use a password, or an SSH key file (no password needed for GCP, AWS, etc.) |
| ⚡ **Real-time output** | See command results as they run |
| 🤖 **AI integration** | Works with Claude Desktop and Cursor IDE |
| 🎨 **Natural language** | "Show disk usage", "List Docker containers", "Restart nginx" |
| 📦 **Minimal setup** | Just add a few lines to your config—no complex installation |

---

## 📋 What You Need

- **Node.js v18 or newer** — [Download here](https://nodejs.org/) (choose LTS)
- **Claude Desktop** or **Cursor IDE**
- A remote server with SSH access (IP address or hostname, username, and either password or SSH key)

### Installing Node.js (if you don't have it)

**Windows:**  
1. Go to [nodejs.org](https://nodejs.org/) and download the LTS version  
2. Run the installer  
3. Open a new terminal and type `node --version` to confirm

**macOS:**
```bash
brew install node
```

**Linux (Ubuntu/Debian):**
```bash
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs
```

---

## 🚀 Quick Install (Recommended)

**For you or your AI agent:** Add the following to your MCP config file, then restart your app.

### Where is the config file?

| App | Windows | macOS / Linux |
|-----|---------|---------------|
| **Claude Desktop** | `%APPDATA%\Claude\claude_desktop_config.json` | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| **Cursor IDE** | `%USERPROFILE%\.cursor\mcp.json` | `~/.cursor/mcp.json` |

*Tip: In Windows, press `Win+R`, type `%APPDATA%\Claude` and press Enter to open the Claude folder.*

### What to add

Open the config file (create it if it doesn't exist) and add:

```json
{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": ["-y", "git+https://github.com/mertcankaraoglu/ssh-mcp.git#main"]
    }
  }
}
```

If you already have other MCP servers, add the `"ssh"` block inside the existing `"mcpServers"` object.

### After adding

1. Save the file  
2. Restart Claude Desktop or Cursor  
3. You're done! Ask your AI to connect to a server.

---

## 💡 How to Use

### Step 1: Connect

Tell your AI how to connect. You need either a **password** or an **SSH key**.

**With password:**
```
Connect to 192.168.1.100, username ubuntu, password mypassword
```

**With SSH key (e.g. Google Cloud, AWS):**
```
Connect to 34.123.45.67 using SSH key at ~/.ssh/google_compute_engine, username myuser
```

### Step 2: Run commands

Once connected, ask naturally:

| You say | AI runs |
|---------|---------|
| "Show disk usage" | `df -h` |
| "List Docker containers" | `docker ps` |
| "Last 10 log lines" | `tail -n 10 /var/log/syslog` |
| "What's the uptime?" | `uptime` |

### Step 3: Disconnect

```
Close SSH connection
```

### 📝 Example conversation

Here's a full example of how a typical session might go:

| You | AI |
|-----|-----|
| *"Connect to my server at 192.168.1.100, username ubuntu, password mypass123"* | *"Connected successfully. What would you like me to run?"* |
| *"Show disk usage"* | *Runs `df -h` and shows the output* |
| *"List running Docker containers"* | *Runs `docker ps` and shows the list* |
| *"Close the SSH connection"* | *"Connection closed."* |

---

## 🔐 Authentication Options

You must provide **either** a password **or** an SSH key. Password is **not required** when using a key.

### Option 1: Password

Provide: `host`, `username`, `password`

### Option 2: SSH key (recommended for cloud VMs)

**By file path** (e.g. `~/.ssh/id_rsa`):
```
host, username, privateKeyPath: "~/.ssh/id_rsa"
```

**By key content** (PEM string):
```
host, username, privateKey: "-----BEGIN OPENSSH PRIVATE KEY-----\n..."
```

**Encrypted key:** Add `passphrase` when your key is protected.

### By platform

| Platform | Typical setup |
|----------|---------------|
| 🟢 **Google Cloud VM** | `privateKeyPath: "~/.ssh/google_compute_engine"` |
| 🟠 **AWS EC2** | `privateKeyPath: "~/.ssh/my-key.pem"` |
| 🔵 **DigitalOcean** | `privateKeyPath: "~/.ssh/id_rsa"` (or your Droplet key) |
| 🖥️ **Self-hosted / VPS** | Password or `~/.ssh/id_rsa` |

---

## 🛠️ Available Tools

| Tool | What it does |
|------|--------------|
| `ssh_connect` | Connects to the SSH server (host, username, password or key) |
| `ssh_exec` | Runs a command on the connected server |
| `ssh_disconnect` | Closes the connection |

---

## 📂 Manual Installation

If you prefer to clone the repo and run it locally:

```bash
git clone https://github.com/mertcankaraoglu/ssh-mcp.git
cd ssh-mcp
npm install
```

Then in your MCP config, use the local path:

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

*Replace the path with your actual path. On Windows use double backslashes `\\`.*

---

## 🔧 How It Works

```
┌─────────────────┐
│ Claude / Cursor │  ← You talk here
└────────┬────────┘
         │ MCP Protocol
┌────────▼────────┐
│  SSH MCP Server │  ← This project
└────────┬────────┘
         │ SSH
┌────────▼────────┐
│ Your Server     │  ← Commands run here
└─────────────────┘
```

---

## 🛡️ Security

- Passwords and keys are **not** stored in config files—they're only used when you connect  
- All connections use standard SSH encryption  
- Prefer **SSH key** auth for production (GCP, AWS, etc.)  
- Never commit private keys to git

---

## 🗺️ Roadmap

- [x] SSH key support
- [ ] Multi-server management
- [ ] SFTP file transfer
- [ ] Port forwarding
- [ ] Session save/load

---

## ❓ Troubleshooting

| Problem | What to try |
|---------|-------------|
| **"Config file not found"** | Create the file if it doesn't exist. For Cursor: `~/.cursor/mcp.json` or `%USERPROFILE%\.cursor\mcp.json` |
| **"Node not found"** | Install Node.js v18+ from [nodejs.org](https://nodejs.org/). Restart your app after installing. |
| **"Connection failed"** | Check host, username, and password/key. For cloud VMs, ensure your SSH key path is correct (e.g. `~/.ssh/google_compute_engine`). |
| **"MCP server not loading"** | Restart Claude Desktop or Cursor completely after editing the config. |

---

## 🤝 Contributing

Contributions are welcome!

1. Fork the repo  
2. Create a branch (`git checkout -b feature/amazing`)  
3. Commit (`git commit -m 'feat: Add amazing feature'`)  
4. Push (`git push origin feature/amazing`)  
5. Open a Pull Request  

---

## 📝 License

MIT — see [LICENSE](LICENSE) for details.

---

## 🙏 Thanks

- [Anthropic](https://anthropic.com) — Claude & MCP  
- [Model Context Protocol](https://modelcontextprotocol.io) — Documentation  
- [ssh2](https://github.com/mscdex/ssh2) — Node.js SSH client  

---

**[Türkçe](README.tr.md)** | ⭐ If this helps you, consider starring the repo!