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"]
}

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

📋 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?

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:

Step 3: Disconnect

Close SSH connection

📝 Example conversation

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

🔐 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

🛠️ Available Tools

📂 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

🤝 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!