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

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 (Go binary).

From Source

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

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

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

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

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