MCP SSH Server - Remote Server Control for Claude

🚀 Connect Claude AI to your remote server via SSH. Read files, write files, execute commands, and manage your server directly from Claude Desktop!

Features

✅ Full SSH Access - Connect to any SSH server
✅ SSH Key Generator - Generate keys directly in installer
✅ Multiple Servers - Add, remove, and manage unlimited servers
✅ Easy Server Management - Add servers by just talking to Claude
✅ No Code Editing - Manage everything through conversation
✅ File Operations - Read, write, and manage files
✅ Command Execution - Run any command on your server
✅ Directory Listing - Browse your server's filesystem
✅ Auto-Updates - Automatically checks for updates every 12 hours
✅ Secure - Supports SSH keys and password authentication
✅ Easy Installation - Simple GUI installer for Windows

Quick Start

1. Download Installer

Download the latest MCP-SSH-Installer.exe from Releases

2. Run Installer

1. Enter first server details:
   • Server name (e.g., "production")
   • Server IP, port, and username
   • Choose authentication:
     • SSH Key (Recommended):
       • Click "🔑 Generate New" to create a new SSH key
       • Or click "Browse" to select an existing key
       • Copy the public key shown and add it to your server (instructions provided)
     • Password: Enter your SSH password
2. Click "➕ Add Server"
3. Repeat to add more servers (optional)
4. Click "Install"

3. Restart Claude Desktop

Close and reopen Claude Desktop. You're done! 🎉

Usage Examples

Once installed, you can ask Claude:

Managing Servers

• "List all my servers" - Show all configured servers
• "Add a new server called staging with IP 192.168.1.50, username admin, password mypass123"
• "Add server named aws-prod, IP 54.123.45.67, port 2222, user root, using SSH key C:\Users\Me\.ssh\aws_key"
• "Remove server staging" - Delete a server
• "Edit server production, change IP to 10.0.0.5" - Update server details
• "Switch to development server" - Change active server
• "What server am I connected to?" - Show current server

File Operations

• "List files in /var/www"
• "Read the file /etc/nginx/nginx.conf"
• "Create a file /home/user/test.txt with content 'Hello World'"
• "Show me the last 50 lines of /var/log/nginx/error.log"

Commands

• "Execute command: df -h" - Check disk space
• "Run: systemctl status nginx" - Check service status
• "Execute: top -bn1 | head -20" - Check system resources
• "Show me running Docker containers"

Manual Installation

If you prefer manual installation:

# Clone the repository
git clone https://github.com/MaraBank/mcpaddon.git
cd mcpaddon

# Install dependencies
npm install

# Create your config.json
cp config.example.json config.json
# Edit config.json with your server details

# Add to Claude Desktop config
# Windows: %APPDATA%\Claude\claude_desktop_config.json
# Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
# Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ssh-filesystem": {
      "command": "node",
      "args": ["C:\\path\\to\\mcpaddon\\server.js"]
    }
  }
}

Multiple Servers

You can add servers directly through Claude without editing any files!

Example conversation:

You: "Add a new server called production with IP 123.45.67.89, username root, using SSH key C:\Users\Me\.ssh\id_rsa"

Claude: ✓ Server "production" added successfully!

        Details:
        - IP: 123.45.67.89
        - Port: 22
        - Username: root
        - Auth: key

        Use "switch to production" to activate it.

You: "Add server dev, IP 192.168.1.100, port 22, user admin, password secret123"

Claude: ✓ Server "dev" added successfully!

You: "List all servers"

Claude: Available servers:
        ✓ production - root@123.45.67.89:22
          dev - admin@192.168.1.100:22

        (✓ = currently active)

You: "Switch to dev"

Claude: Switched to: dev (admin@192.168.1.100)

Or manually create config.json:

{
  "active_server": "production",
  "servers": [
    {
      "name": "production",
      "server_ip": "123.45.67.89",
      "server_port": 22,
      "username": "root",
      "auth_method": "key",
      "ssh_key_path": "C:\\Users\\YourName\\.ssh\\id_ed25519",
      "password": ""
    },
    {
      "name": "development",
      "server_ip": "192.168.1.100",
      "server_port": 22,
      "username": "dev",
      "auth_method": "password",
      "ssh_key_path": "",
      "password": "yourpassword"
    },
    {
      "name": "staging",
      "server_ip": "10.0.0.5",
      "server_port": 2222,
      "username": "ubuntu",
      "auth_method": "key",
      "ssh_key_path": "C:\\Users\\YourName\\.ssh\\staging_key",
      "password": ""
    }
  ],
  "auto_update": true,
  "github_repo": "https://github.com/MaraBank/mcpaddon",
  "version": "2.0.0"
}

Managing servers through Claude:

• "List all servers" - See all your servers
• "Switch to development" - Change active server
• "What server am I on?" - Show current server
• "Add server staging with IP 10.0.0.5, user ubuntu, password test123" - Add new server
• "Remove server old-server" - Delete a server
• "Edit server production, change password to newpass456" - Update server

Auto-Update

The server automatically checks for updates every 12 hours. When an update is available, it will:

1. Download the latest version from GitHub
2. Install updated dependencies
3. Notify you to restart Claude Desktop

Manual update:

cd mcpaddon
git pull
npm install
# Restart Claude Desktop

Security

⚠️ Important Security Notes:

Best Practices

• ✅ Use SSH Keys - Much more secure than passwords
• ✅ Create Limited User - Don't use root for everything
• ✅ Enable Firewall - Restrict SSH port access
• ✅ Use Strong Passwords - If you must use password auth
• ✅ Keep config.json Private - Contains your credentials
• ✅ Regular Updates - Keep the MCP server updated

Setting up SSH Keys

Option 1: Generate in Installer (Easiest)

1. In the installer, select "SSH Key"
2. Click "🔑 Generate New"
3. A window will show your public key
4. Click "📋 Copy Key"
5. On your server, run these commands:

# Connect to your server
ssh username@your-server-ip

# Create .ssh directory if it doesn't exist
mkdir -p ~/.ssh

# Open authorized_keys file
nano ~/.ssh/authorized_keys

# Paste your public key (right-click in terminal)
# Save: Ctrl+X, then Y, then Enter

# Set correct permissions
chmod 600 ~/.ssh/authorized_keys
chmod 700 ~/.ssh

# Exit
exit

Option 2: Manual Generation

On Windows (PowerShell):

# Generate key
ssh-keygen -t ed25519 -C "your_email@example.com"

# View public key
type $env:USERPROFILE\.ssh\id_ed25519.pub

# Copy to server
ssh-copy-id username@your-server-ip

On Mac/Linux:

# Generate key
ssh-keygen -t ed25519 -C "your_email@example.com"

# View public key
cat ~/.ssh/id_ed25519.pub

# Copy to server
ssh-copy-id username@your-server-ip

Additional Security

Disable Password Authentication (after SSH keys work):

# On your server
sudo nano /etc/ssh/sshd_config

# Change these lines:
PasswordAuthentication no
PubkeyAuthentication yes
PermitRootLogin prohibit-password

# Restart SSH
sudo systemctl restart sshd

Use a Non-Standard SSH Port:

# Edit SSH config
sudo nano /etc/ssh/sshd_config

# Change port (e.g., to 2222)
Port 2222

# Restart SSH
sudo systemctl restart sshd

# Update firewall
sudo ufw allow 2222/tcp

Troubleshooting

Connection Issues

Problem: Cannot connect to server

Solutions:

• Verify server IP: ping your-server-ip
• Check SSH port: telnet your-server-ip 22
• Test SSH directly: ssh username@your-server-ip
• Check firewall: sudo ufw status
• Verify credentials are correct

Problem: "Permission denied (publickey)"

Solutions:

• Check key path is correct
• Verify key has correct permissions: chmod 600 ~/.ssh/id_ed25519
• Ensure public key is on server: cat ~/.ssh/authorized_keys
• Check server SSH config allows key auth

Claude Desktop Issues

Problem: Claude doesn't see the server

Solutions:

• Verify config path in claude_desktop_config.json
• Check the path uses double backslashes on Windows: C:\\path\\to\\server.js
• Restart Claude Desktop completely (check system tray)
• Check for errors in Claude Desktop logs

Problem: "config.json not found"

Solutions:

• Ensure config.json exists in the installation directory
• Check installer completed successfully
• Manually create config.json from config.example.json

Update Issues

Problem: Auto-update not working

Solutions:

• Ensure Git is installed: git --version
• Check internet connection
• Verify GitHub repository URL is correct
• Check file permissions on installation directory

Problem: Update failed mid-way

Solutions:

cd mcpaddon
git stash  # Save local changes
git pull origin main
npm install
# Restart Claude Desktop

Performance Issues

Problem: Slow file operations

Solutions:

• Check network connection speed
• Verify server isn't under heavy load
• Use execute_command for batch operations
• Consider compressing large files before transfer

Development

Want to contribute or customize? Here's how:

Setup Development Environment

# Clone repository
git clone https://github.com/MaraBank/mcpaddon.git
cd mcpaddon

# Install dependencies
npm install

# Create test config
cp config.example.json config.json
# Edit config.json with test server details

# Run in development mode
node server.js

Project Structure

mcpaddon/
├── server.js              # Main MCP server code
├── package.json           # NPM dependencies and metadata
├── config.json           # User's server configurations (not in git)
├── config.example.json   # Example configuration
├── .gitignore           # Files to exclude from git
└── README.md            # This file

Adding New Features

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes
4. Test thoroughly
5. Commit: git commit -m "Add feature-name"
6. Push: git push origin feature-name
7. Create a Pull Request

Testing

# Test SSH connection
node server.js

# In Claude Desktop, try:
# - "List all servers"
# - "Execute command: echo test"
# - "Read file /etc/hostname"

Server Management Commands

All server management can be done through natural conversation with Claude:

Adding Servers

With SSH Key:

"Add a server called aws-prod with IP 54.23.45.67, username ubuntu, using SSH key C:\Users\Me\.ssh\aws.pem"

"Add server named linode, IP 23.92.28.47, port 2222, user root, SSH key C:\Users\Me\.ssh\linode_key"

With Password:

"Add server local-dev, IP 192.168.1.50, port 2222, user admin, password mySecretPass"

"Add server named staging with IP 10.0.0.5, username deploy, password staging123"

Minimal (uses defaults - port 22):

"Add server test with IP 10.0.0.1, user root, password 123456"

Editing Servers

Change IP:

"Edit server production, change IP to 55.66.77.88"

Change Password:

"Edit server staging, update password to newPassword123"

Change Authentication Method:

"Edit server dev, change to SSH key C:\Users\Me\.ssh\new_key"

Change Multiple Fields:

"Edit server dev, change IP to 192.168.2.100, username to developer, port to 2222"

Removing Servers

"Remove server old-staging"
"Delete the server named test-server"
"Remove server backup"

Switching Servers

"Switch to production"
"Change to development server"
"Use the staging server"
"Connect to aws-prod"

Listing Servers

"Show all servers"
"List my servers"
"What servers do I have?"
"Display all configured servers"

Current Server

"What server am I on?"
"Show current server"
"Which server is active?"

Advanced Usage

Batch Operations

Execute multiple commands:

"On production server, run these commands:
1. Check disk space
2. Show running processes
3. Display last 20 log lines"

File Management

"Read the nginx config and save it to a local backup"
"Update the /etc/hosts file on staging server"
"List all log files in /var/log and show their sizes"

Server Monitoring

"Check CPU and memory usage on all servers"
"Show me the last 100 lines of the error log"
"What processes are using the most memory?"

Deployment Tasks

"On production, pull latest code from git, install dependencies, and restart the service"
"Deploy the new version to staging server"
"Backup the database on production server"

API Reference

Available Tools

The MCP server exposes these tools to Claude:

list_servers

Lists all configured servers with their connection details.

add_server

Adds a new server configuration.

Parameters:

• name (string, required) - Server name
• server_ip (string, required) - IP address
• server_port (number, optional) - SSH port (default: 22)
• username (string, required) - SSH username
• auth_method (string, required) - "key" or "password"
• ssh_key_path (string, optional) - Path to private key
• password (string, optional) - SSH password

remove_server

Removes a server configuration.

Parameters:

• name (string, required) - Server name to remove

edit_server

Edits an existing server configuration.

Parameters:

• name (string, required) - Server name to edit
• All other parameters optional

switch_server

Switches to a different server.

Parameters:

• server_name (string, required) - Server name to switch to

current_server

Shows the currently active server.

read_file

Reads a file from the remote server.

Parameters:

• path (string, required) - Absolute path to file

write_file

Writes content to a file on the remote server.

Parameters:

• path (string, required) - Absolute path to file
• content (string, required) - Content to write

list_directory

Lists contents of a directory.

Parameters:

• path (string, required) - Absolute path to directory

execute_command

Executes a shell command on the remote server.

Parameters:

• command (string, required) - Command to execute

Version History

v2.0.0 (2024-12-10) - Current

• ✨ Generate SSH keys directly in installer
• ✨ Visual guide for adding keys to server
• ✨ Add/Remove/Edit servers through Claude conversation
• ✨ No code editing required for server management
• ✨ Multiple servers support with easy switching
• ✨ Switch between servers easily
• ✨ Auto-update every 12 hours from GitHub
• ✨ GitHub integration for seamless updates
• ✨ Professional GUI installer for Windows
• ✨ Config file support for flexible configuration
• 🐛 Bug fixes and stability improvements
• 📚 Comprehensive documentation

v1.0.0 (2024-11-15)

• 🎉 Initial release
• Basic SSH file operations (read/write)
• Command execution on remote servers
• Single server configuration
• Manual installation only

Roadmap

Planned Features

• 🔜 Multi-platform Support - Mac and Linux installers
• 🔜 SSH Tunnel Management - Create and manage SSH tunnels
• 🔜 File Transfer Progress - Visual progress for large file operations
• 🔜 Server Groups - Organize servers into groups
• 🔜 Scheduled Commands - Run commands on a schedule
• 🔜 Server Health Monitoring - Automatic health checks
• 🔜 Backup Management - Automated backup solutions
• 🔜 Log Streaming - Real-time log viewing
• 🔜 Container Management - Docker/Podman integration
• 🔜 Database Tools - Direct database query support

Request a Feature

Have an idea? Open an issue with the "enhancement" label!

FAQ

Q: Is my data secure?
A: Yes! Your credentials are stored locally in config.json and never sent anywhere except directly to your servers. The auto-update only downloads code from GitHub.

Q: Can I use this with multiple Claude Desktop instances?
A: Yes, but each instance needs its own installation and config.

Q: Does this work on Mac/Linux?
A: The MCP server works on all platforms. Currently, the GUI installer is Windows-only, but you can do manual installation on Mac/Linux.

Q: How much does it cost?
A: It's completely free and open-source!

Q: Can I connect to servers behind a firewall?
A: Yes, as long as your machine can reach the server via SSH.

Q: What if I have multiple SSH keys?
A: You can specify different keys for each server.

Q: Can Claude see my passwords?
A: Claude can only execute the commands you approve. Passwords are stored locally in config.json.

Q: How do I update to a new version?
A: Just wait! Auto-update checks every 12 hours. Or manually: cd mcpaddon && git pull && npm install

Q: Can I disable auto-update?
A: Yes, set "auto_update": false in config.json.

Q: What if something breaks after an update?
A: The auto-update creates a backup. You can also roll back: git checkout v2.0.0

License

MIT License

Copyright (c) 2024 MaraBank

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Support

Having issues or questions?

• 📖 Check the Wiki for detailed guides
• 🐛 Report bugs in Issues
• 💬 Join discussions in Discussions
• 📧 Contact: Create an issue

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Acknowledgments

• Built with Anthropic's MCP SDK
• SSH functionality powered by ssh2
• Inspired by the amazing Claude AI community

Star History

If this project helped you, please consider giving it a star! ⭐

---

Made with ❤️ by MaraBank

🚀 Get Started Now | 📖 Read the Docs | 💬 Get Help