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

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

1. 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 (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 and download the LTS version
2. Run the installer
3. Open a new terminal and type node --version to confirm

macOS:

brew install node

Linux (Ubuntu/Debian):

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:

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

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

Then in your MCP config, use the local path:

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

• 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. 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 for details.

---

🙏 Thanks

• Anthropic — Claude & MCP
• Model Context Protocol — Documentation
• ssh2 — Node.js SSH client

---

Türkçe | ⭐ If this helps you, consider starring the repo!