# ssh-mcp
## 基本信息
- Slug: `rpavez-ssh-mcp`
- Source: modelscope
- Publisher: @rpavez/ssh-mcp
- Categories: shell-access / cloud-platforms / command-line
- Hosted: No
- License: Unknown
- Source URL: https://www.modelscope.cn/mcp/servers/@rpavez/ssh-mcp
## 简介
暂无描述。
## 安装提示

```bash
cd mcp-remote
```

## MCP 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:**…