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