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:

Example with AWS EC2:

Example with Google Cloud:

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:

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

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:

Usage

Starting the Server

The server will output:

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

   • 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 in ~/.ssh/config

3. Check SSH key has access to the remote server

Development

Project Structure

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

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.