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:

   cd mcp-remote
   

2. Install dependencies:

   npm install
   

3. Start the MCP server:

   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:

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:

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:

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:

{
  "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:

# 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

# 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:

   lsof -i :3000
   

2. Check Node.js version:

   node --version  # Should be 16+
   

Cursor Can't Connect

1. Verify server is running:

   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:

   ssh dev
   

2. Verify SSH config:

   ssh -F ~/.ssh/config dev
   

3. Check SSH key permissions:

   ls -la ~/.ssh/id_rsa
   chmod 600 ~/.ssh/id_rsa
   

4. Verify the host alias exists:

   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

# 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.