MCP Remote Server

# MCP Remote Server A Model Context Protocol (MCP) server that enables Cursor IDE to execute SSH commands on remote servers and manage Google Cloud Platform (GCE) instances. This server provides a seamless integration between Cursor and your remote infrastructure. ## Features - 🔐 **SSH Command Execution**: Run commands on remote servers via SSH - ☁️ **GCE Instance Management**: Start and stop Google Cloud Compute Engine instances - 🔄 **Connection Pooling**: Reuses SSH connections for improved performance - 📝 **SSH Config Integration**: Uses your existing `~/.ssh/config` for host configuration - 🚀 **MCP Protocol**: Full support for Model Context Protocol v2025-06-18 ## Prerequisites - Node.js 16+ installed - SSH access configured to your remote server - Google Cloud Platform credentials (for GCE features) - Cursor IDE installed ## Installation 1. **Clone or navigate to the repository:** ```bash cd mcp-remote ``` 2. **Install dependencies:** ```bash npm install ``` 3. **Start the MCP server:** ```bash node src/index.js ``` The server will start on `http://localhost:3000` by default. ## Configuration ### 1. SSH Configuration First, you need to configure your SSH connection in `~/.ssh/config`. The server always uses the host alias `dev` regardless of what you specify in prompts. Create or edit `~/.ssh/config`: ```ssh-config Host dev HostName your-server.example.com User your-username Port 22 IdentityFile ~/.ssh/id_rsa # Optional: Add additional SSH options # ServerAliveInterval 60 # ServerAliveCountMax 3 # StrictHostKeyChecking no # UserKnownHostsFile ~/.ssh/known_hosts ``` **Example with AWS EC2:** ```ssh-config Host dev HostName ec2-12-34-56-78.compute-1.amazonaws.com User ubuntu Port 22 IdentityFile ~/.ssh/my-aws-key.pem ``` **Example with Google Cloud:** ```ssh-config Host dev HostName 34.123.45.67 User root Port 22 IdentityFile ~/.ssh/gcp-key.pem ``` **Important Notes:** - The host alias **must** be named `dev` (all lowercase) - The server will **always** connect to `dev` regardless of the host you specify in prompts - Make sure your SSH key has proper permissions: `chmod 600 ~/.ssh/id_rsa` ### 2. Cursor MCP Configuration Configure Cursor to connect to the MCP server by editing `~/.cursor/mcp.json`: ```json { "mcpServers": { "local-mcp": { "name": "Local MCP", "url": "http://localhost:3000", "description": "Runs SSH commands and manages GCE instances", "apiKeyHeader": "x-api-key", "apiKeyValue": "8BOe6KshR5Eq0otTSjSGMEf5P1edKcq" } } } ``` **Configuration Fields:** - `name`: Display name for the MCP server in Cursor - `url`: The URL where your MCP server is running (default: `http://localhost:3000`) - `description`: Description of what the server does - `apiKeyHeader`: Header name for API authentication (currently optional) - `apiKeyValue`: API key value for authentication (currently optional) **After modifying `mcp.json`:** 1. Save the file 2. Restart Cursor IDE 3. The MCP server should appear in Cursor's tool list ### 3. Environment Variables (Optional) You can set environment variables to customize behavior: ```bash # SSH Configuration (optional - defaults to ~/.ssh/id_rsa) export SSH_USERNAME=your-username export SSH_PRIVATE_KEY_PATH=~/.ssh/custom_key # Server Configuration export PORT=3000 # GCP Configuration (for GCE features) export GOOGLE_APPLICATION_CREDENTIALS=/path/to/gcp-credentials.json ``` ## Usage ### Starting the Server ```bash # Start the server node src/index.js # Or with custom port PORT=8080 node src/index.js ``` The server will output: ``` MCP server running on http://localhost:3000 Ready to accept MCP connections from Cursor ``` ### Using in Cursor IDE Once configured, you can use the MCP tools directly in Cursor: 1. **Run SSH Commands:** - Ask Cursor: "Check disk usage on server1.example.com" - The server will automatically connect to `dev` and execute the command - Example: "Run `df -h` on my remote server" 2. **Manage GCE Instances:** - Ask Cursor: "Start instance my-vm in project my-project, zone us-central1-a" - Ask Cursor: "Stop instance my-vm in project my-project, zone us-central1-a" ### Available Tools 1. **run_command** - Execute SSH commands on the remote server - Always connects to `dev` from `~/.ssh/config` - Parameters: - `host`: Ignored (always uses `dev`) - `cmdKey`: The command to execute (e.g., `df -h`, `ls -la`) 2. **start_instance** - Start a GCE instance - Parameters: - `project`: GCP project ID - `zone`: GCE zone (e.g., `us-central1-a`) - `instance`: Instance name 3. **stop_instance** - Stop a GCE instance - Parameters: - `project`: GCP project ID - `zone`: GCE zone - `instance`: Instance name ## Architecture ### Connection Pooling The server maintains a pool of SSH connections to improve performance: - Connections are reused across multiple commands - Connections are kept alive with keepalive settings - Automatic cleanup on connection errors ### SSH Config Integration The server reads connection details from `~/.ssh/config`: - Hostname, port, username, and identity file - Supports all standard SSH config options - Handles `~` expansion in file paths - Supports multiple IdentityFile entries (uses the first one) ## Troubleshooting ### Server Won't Start 1. **Check if port is already in use:** ```bash lsof -i :3000 ``` 2. **Check Node.js version:** ```bash node --version # Should be 16+ ``` ### Cursor Can't Connect 1. **Verify server is running:** ```bash curl http://localhost:3000 ``` 2. **Check `~/.cursor/mcp.json` syntax:** - Ensure valid JSON - Verify the URL matches your server 3. **Restart Cursor IDE** after modifying `mcp.json` ### SSH Connection Issues 1. **Test SSH connection manually:** ```bash ssh dev ``` 2. **Verify SSH config:** ```bash ssh -F ~/.ssh/config dev ``` 3. **Check SSH key permissions:** ```bash ls -la ~/.ssh/id_rsa chmod 600 ~/.ssh/id_rsa ``` 4. **Verify the host alias exists:** ```bash grep -A 5 "^Host dev" ~/.ssh/config ``` ### Commands Not Executing 1. **Check server logs** for error messages 2. **Verify the `dev` host is properly configured** in `~/.ssh/config` 3. **Check SSH key has access** to the remote server ## Development ### Project Structure ``` mcp-remote/ ├── src/ │ ├── index.js # Main MCP server │ ├── ssh.js # SSH connection handling │ └── gcp.js # GCP instance management ├── package.json ├── README.md └── .gitignore ``` ### Adding New Tools To add new MCP tools: 1. Add tool definition to the `tools` array in `src/index.js` 2. Add handler in the `tools/call` case 3. Implement the functionality in the appropriate module ### Testing ```bash # Test SSH connection node -e "const {runRemoteCommand} = require('./src/ssh'); runRemoteCommand({host: 'dev', command: 'echo test'}).then(r => console.log(r));" # Test MCP server curl -X POST http://localhost:3000 \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-06-18"},"id":1}' ``` ## Security Considerations - The server runs on `localhost:3000` by default (not exposed to network) - SSH credentials are read from `~/.ssh/config` (standard SSH security) - API key authentication is available but currently optional - Consider using environment variables for sensitive data ## License [Add your license here] ## Contributing Contributions are welcome! Please feel free to submit a Pull Request. ## Support For issues and questions: - Check the Troubleshooting section - Review server logs for error messages - Ensure SSH configuration is correct --- **Note**: The server always connects to the `dev` host alias from your SSH config, regardless of the host you specify in prompts. Make sure `dev` is properly configured in `~/.ssh/config`.