impreza-mcp

Model Context Protocol server for Impreza Host. Lets AI coding tools (Claude Code, Cursor, Codex CLI, Continue, Zed, ...) deploy customer-built apps to managed Impreza VPSes without leaving the chat.

When you say "deploy this for me" to Claude with this MCP server loaded, Claude calls impreza_deploy_custom directly — packages your project, uploads it, builds + runs on your Impreza VPS, and reports back the URL.

No-install alternative: if your AI client supports remote MCP connectors (e.g. Claude), you can skip this package and add the hosted connector https://mcp.imprezahost.com/mcp instead — authorize in your Impreza clientarea, no API key and no IP whitelist. It exposes the same full toolset, gated by the scopes you grant on consent (read / deploy / manage). Install this package when you want a local server — e.g. to deploy a project folder straight from your machine, which the hosted connector can't.

Status

Full surface live. All 32 tools shipped — app deployment (14) plus account + crypto balance, domains/DNS, and VPS lifecycle (18) — with a setup wizard that generates ready-to-paste config snippets for 5 AI tools.

Tool	Wraps
Apps & deployments
impreza_list_servers	GET /v1/platform/servers
impreza_list_apps	GET /v1/platform/apps
impreza_list_deployments	GET /v1/platform/deployments + /custom (merged)
impreza_deploy_custom	POST /v1/platform/deployments/custom (3 modes)
impreza_deploy_catalog_app	POST /v1/platform/deployments
impreza_uninstall_deployment	POST .../uninstall
impreza_get_logs	POST .../logs (sync tail, last N lines)
impreza_restart_deployment	POST .../restart
impreza_redeploy_deployment	POST .../custom/{id}/redeploy (in-place rebuild, same domain)
impreza_add_onion	POST .../onion/add
impreza_change_domain	POST .../domain
impreza_git_webhook_status	GET .../custom/{id}/git-webhook
impreza_git_webhook_connect	POST .../custom/{id}/git-webhook/connect
impreza_git_webhook_disconnect	POST .../custom/{id}/git-webhook/disconnect
Account & balance
impreza_account_info	GET /v1/account
impreza_list_services	GET /v1/account/services
impreza_topup	POST /v1/account/topup — top up in BTC / XMR / USDT / TRX
impreza_topup_status	GET /v1/account/topup/{invoice_id}
impreza_topup_payment	GET /v1/account/topup/{invoice_id}/payment — crypto address + amount to pay
Domains & DNS
impreza_domain_check	GET /v1/domains/check
impreza_domain_details	GET /v1/domains/{domain}
impreza_list_dns	GET /v1/domains/{domain}/dns
impreza_add_dns_record	POST /v1/domains/{domain}/dns
impreza_update_dns_record	PUT /v1/domains/{domain}/dns
impreza_delete_dns_record	DELETE /v1/domains/{domain}/dns
impreza_set_nameservers	PUT /v1/domains/{domain}/nameservers
VPS lifecycle (Proxmox)
impreza_vps_status	GET /v1/vps/proxmox/{id}/status
impreza_vps_power	POST /v1/vps/proxmox/{id}/{start|shutdown|reboot|stop}
impreza_vps_list_backups	GET /v1/vps/proxmox/{id}/backups
impreza_vps_create_backup	POST /v1/vps/proxmox/{id}/backups
impreza_vps_list_templates	GET /v1/vps/proxmox/{id}/templates
impreza_vps_reinstall	POST /v1/vps/proxmox/{id}/reinstall — destructive (wipes)

Install + setup

Prerequisites

• Node ≥ 20
• An Impreza Host account with an API key + secret (clientarea → Impreza API). The key's IP factor is per-key: whitelist (default — add this machine's IP), tofu (trust-on-first-use — auto-pins the first IP), or keyonly (no IP factor)

One-shot via npx

No global install needed — npx impreza-mcp works.

Or install globally

npm install -g impreza-mcp

Get a ready-to-paste config snippet

The fastest path: ask the binary itself.

npx impreza-mcp setup --tool claude-code
# also: cursor | continue | zed | codex-cli

The wizard prints the JSON block to drop into your AI tool's MCP config + the exact file path + the post-config step (usually "fully quit + re-open the AI tool"). It does NOT write to disk — paste it yourself so you don't accidentally clobber an existing config with other MCP servers.

Or wire it in manually

Claude Code — add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%/Claude/claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "impreza": {
      "command": "npx",
      "args": ["-y", "impreza-mcp"],
      "env": {
        "IMPREZA_API_KEY": "imp_...",
        "IMPREZA_API_SECRET": "..."
      }
    }
  }
}

Restart Claude Code. The tools appear under the MCP icon.

Cursor — add to ~/.cursor/mcp.json (same shape as above).

Continue — add to ~/.continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "impreza-mcp"],
          "env": {
            "IMPREZA_API_KEY": "imp_...",
            "IMPREZA_API_SECRET": "..."
          }
        }
      }
    ]
  }
}

Zed — add to your settings:

{
  "context_servers": {
    "impreza": {
      "command": {
        "path": "npx",
        "args": ["-y", "impreza-mcp"],
        "env": {
          "IMPREZA_API_KEY": "imp_...",
          "IMPREZA_API_SECRET": "..."
        }
      }
    }
  }
}

Usage in chat

After setup, talk to your AI naturally:

"List my Impreza servers." → calls impreza_list_servers

"Deploy this directory to my Impreza VPS, expose via .onion." → packages the cwd as a Dockerfile-mode custom deploy, uploads, deploys with onion=true, reports the .onion address.

"What apps are running on my agent?" → calls impreza_list_deployments filtered to the right server.

Auth + security

IMPREZA_API_KEY + IMPREZA_API_SECRET live in the AI tool's MCP config env — not in any file on disk owned by impreza-mcp itself. The MCP server holds the secret only in memory and only attaches it as HTTP request headers.

The API key's IP second factor is per-key: leave it on whitelist and add this machine's IP, or pick tofu (auto-pins the first IP) or keyonly (no IP factor) in your Impreza clientarea — so the whitelist step is now optional. Tokens issued via the hosted OAuth connector are scoped and revocable under clientarea → Impreza API → Connected Apps.

Build

npm install
npm run build
# dist/server.js is the entry point

License

MIT — see LICENSE.