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
- 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
- SSH Key (Recommended):
- Click "➕ Add Server"
- Repeat to add more servers (optional)
- 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:
- Download the latest version from GitHub
- Install updated dependencies
- 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)
- In the installer, select "SSH Key"
- Click "🔑 Generate New"
- A window will show your public key
- Click "📋 Copy Key"
- 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.jsonexists in the installation directory - Check installer completed successfully
- Manually create
config.jsonfromconfig.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_commandfor 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
- Fork the repository
- Create a feature branch:
git checkout -b feature-name - Make your changes
- Test thoroughly
- Commit:
git commit -m "Add feature-name" - Push:
git push origin feature-name - 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 nameserver_ip(string, required) - IP addressserver_port(number, optional) - SSH port (default: 22)username(string, required) - SSH usernameauth_method(string, required) - "key" or "password"ssh_key_path(string, optional) - Path to private keypassword(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 filecontent(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.
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - 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