# 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](https://github.com/MaraBank/mcpaddon/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:
```bash
# 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`:
```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:**
```bash
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:
```bash
# 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):
```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:
```bash
# 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):**
```bash
# 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:**
```bash
# 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:**
```bash
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
```bash
# 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
```bash
# 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](https://github.com/MaraBank/mcpaddon/issues/new) 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](https://github.com/MaraBank/mcpaddon/wiki) for detailed guides
- š Report bugs in [Issues](https://github.com/MaraBank/mcpaddon/issues)
- š¬ Join discussions in [Discussions](https://github.com/MaraBank/mcpaddon/discussions)
- š§ Contact: [Create an issue](https://github.com/MaraBank/mcpaddon/issues/new)
## 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](https://github.com/anthropics/mcp)
- SSH functionality powered by [ssh2](https://github.com/mscdex/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](https://github.com/MaraBank)**
**š [Get Started Now](https://github.com/MaraBank/mcpaddon/releases) | š [Read the Docs](https://github.com/MaraBank/mcpaddon#readme) | š¬ [Get Help](https://github.com/MaraBank/mcpaddon/issues)**
