# MCP Impresario

MCP server for Claude Code to execute commands on any remote server over SSH.

**Works with any SSH server you control.** A managed sandbox service with batteries-included environments is coming soon.

## Installation

```bash
npm install -g mcp-impresario
```

This installs:
- `mcp-impresario` - MCP server for Claude Code
- `mcp-impresario-test` - Connection tester

For other agents (Aider, Codex, Goose, Gemini), use the [Impresario CLI](https://github.com/Pharbi/impresario) (Go binary).

### From Source

```bash
git clone https://github.com/Pharbi/mcp-impresario
cd mcp-impresario
npm install
npm run build
```

## Configuration

Add to your Claude Code MCP settings (`~/.claude.json` or project `.claude.json`):

```json
{
  "mcpServers": {
    "remote": {
      "type": "stdio",
      "command": "mcp-impresario",
      "env": {
        "IMPRESARIO_HOST": "your-server.com",
        "IMPRESARIO_PORT": "22",
        "IMPRESARIO_USER": "ubuntu",
        "IMPRESARIO_KEY": "/path/to/your/key"
      }
    }
  }
}
```

If running from source, use the compiled path:

```json
{
  "mcpServers": {
    "remote": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mcp-impresario/dist/index.js"],
      "env": {
        "IMPRESARIO_HOST": "your-server.com",
        "IMPRESARIO_USER": "ubuntu",
        "IMPRESARIO_KEY": "/path/to/your/key"
      }
    }
  }
}
```

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `IMPRESARIO_HOST` | `localhost` | Hostname or IP of remote server |
| `IMPRESARIO_PORT` | `22` | SSH port |
| `IMPRESARIO_USER` | `ubuntu` | SSH username |
| `IMPRESARIO_KEY` | (none) | Path to SSH private key (optional if using ssh-agent) |
| `IMPRESARIO_KNOWN_HOSTS` | (none) | Path to a custom known_hosts file (see below) |
| `IMPRESARIO_STRICT_HOST_KEY` | `yes` | Set to `no` to disable host key checking |

### Host Key Management

By default, Impresario uses your system's known_hosts file with strict host key checking.

For ephemeral VPS instances that you spin up and tear down frequently, use a dedicated known_hosts file to avoid polluting your main `~/.ssh/known_hosts`:

```json
{
  "mcpServers": {
    "remote": {
      "type": "stdio",
      "command": "mcp-impresario",
      "env": {
        "IMPRESARIO_HOST": "your-server.com",
        "IMPRESARIO_USER": "ubuntu",
        "IMPRESARIO_KEY": "/path/to/your/key",
        "IMPRESARIO_KNOWN_HOSTS": "~/.ssh/impresario_known_hosts"
      }
    }
  }
}
```

When using a custom known_hosts file:
- New host keys are automatically accepted and saved
- Changed host keys are rejected (MITM protection)
- Your system known_hosts remains untouched

## Test Connection

```bash
export IMPRESARIO_HOST=your-server.com
mcp-impresario-test
```

## Available Tools

Once configured, Claude Code gains these tools:

| Tool | Description |
|------|-------------|
| `remote_exec` | Execute any command on the remote server |
| `remote_file_read` | Read a file from the remote server |
| `remote_file_write` | Write a file to the remote server |
| `remote_ls` | List directory contents |
| `remote_info` | Show current connection details |

## Usage Examples

After restarting Claude Code, you can ask:

- "Run `git clone https://github.com/user/repo` on the remote server"
- "Create a Python script on the remote and execute it"
- "Check what's in the home directory on the remote"
- "Read the package.json from the remote project"

## Works with Any Server

This MCP server works with any SSH-accessible machine:

- Your own VPS (DigitalOcean, Linode, Hetzner)
- Cloud instances (EC2, GCP, Azure)
- Home servers or Raspberry Pi

**Requirements:** SSH server running, key authentication configured.

## License

MIT