breezedeploy-mcp

Deploy apps from inside your AI chat. Say "deploy this" in Claude, Cursor, ChatGPT, Copilot, or Windsurf and get a live HTTPS URL — Docker images or git repos, with managed Postgres, on EU infrastructure (breezedeploy.dev).

This is a Model Context Protocol server for the breezedeploy control plane.

Quick start

1. Get an API key (free, no credit card): sign up at panel.breezedeploy.dev/signup — your key is shown once.
2. Add the server to your client:

Claude Code

claude mcp add breezedeploy \
  --env CONTROL_PLANE_API_KEY=hk_your_key \
  -- npx -y breezedeploy-mcp

Codex CLI

codex mcp add breezedeploy \
  --env CONTROL_PLANE_API_KEY=hk_your_key \
  -- npx -y breezedeploy-mcp

Prefer a config file? Add this block to ~/.codex/config.toml:

[mcp_servers.breezedeploy]
command = "npx"
args = ["-y", "breezedeploy-mcp"]
env = { CONTROL_PLANE_API_KEY = "hk_your_key" }

Claude Desktop / Cursor / Windsurf / any MCP client (JSON config)

Add this stdio server to the client's MCP config (~/.cursor/mcp.json, claude_desktop_config.json, …):

{
  "mcpServers": {
    "breezedeploy": {
      "command": "npx",
      "args": ["-y", "breezedeploy-mcp"],
      "env": { "CONTROL_PLANE_API_KEY": "hk_your_key" }
    }
  }
}

On Windows, some clients (e.g. Claude Desktop) need npx wrapped in cmd:

{
  "mcpServers": {
    "breezedeploy": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "breezedeploy-mcp"],
      "env": { "CONTROL_PLANE_API_KEY": "hk_your_key" }
    }
  }
}

Any other AI agent

Point it at the hosted setup skill and let it wire everything up: panel.breezedeploy.dev/connect/SKILL.md.

3. Deploy something:

"Deploy the image nginxdemos/hello as hello in project demo." → https://hello.apps.breezedeploy.dev

"Build and deploy https://github.com/me/my-app — call it myapp." → Nixpacks builds the repo, ships it, returns the URL (private repo? add a token, e.g. a GitHub PAT — used only to clone, never stored)

"Give project demo a Postgres database." → future deploys get DATABASE_URL injected automatically

Deploy a local folder (no git, no Docker)

The simplest path: point it at a folder and go. No git repo, no Docker, no Dockerfile. The folder is packed into a tarball, uploaded, and built server-side with Nixpacks (which auto-detects Node, Python, Go, Rust, …).

From your AI chat, just ask — this uses the deploy_source tool:

"Deploy this folder as my-site." (or "deploy ./web as my-site") → the folder is uploaded, built, and returns https://my-site.apps.breezedeploy.dev

Prefer the terminal? Same thing with breeze up:

CONTROL_PLANE_API_KEY=<your-key> npx -y breezedeploy-mcp up --app my-site
# → https://my-site.apps.breezedeploy.dev
# deploy a subfolder, on a custom port, with env:
npx -y breezedeploy-mcp up --app my-site --dir ./web --port 3000 --env NODE_ENV=production
# API apps can name a readiness endpoint that returns 2xx/3xx:
npx -y breezedeploy-mcp up --app my-api --readiness-path /health
# → https://my-api.apps.breezedeploy.dev

Flags: --dir <path> (folder to deploy, default .), --port <n>, --env KEY=VALUE (repeatable), --project <name>, --mode reserved, --size <key>, --readiness-path <path> (for example /health for an API app), --release-command <cmd> (runs before the new version goes live, e.g. a DB migration against the injected DATABASE_URL; non-zero exit aborts the deploy and the old version keeps serving). Heavy/secret files are excluded automatically: node_modules, .git, dist, build, .next, .nuxt, .svelte-kit, .venv, __pycache__, .DS_Store, *.log, and .env / .env.* (your secrets stay on your machine — set them with --env / the tool's env).

Push a local image (no git, no public registry)

Chat can't carry image bytes, so this is a terminal command. Build on your own machine and ship the image straight to breezedeploy — nothing is public:

docker build -t my-app .
CONTROL_PLANE_API_KEY=<your-key> npx -y breezedeploy-mcp push --app my-app
# → https://my-app.apps.breezedeploy.dev
# if the image's root is not a health endpoint:
npx -y breezedeploy-mcp push --app my-api --readiness-path /health
# → https://my-api.apps.breezedeploy.dev

Flags: --port <n> (non-8080 port), --env KEY=VALUE (repeatable), --project <name>, --image <ref> (local tag to ship), --mode reserved, --readiness-path <path> (for example /health for an API app). Requires Docker locally. (Already have a private registry image on Docker Hub / GHCR? Pass registryAuth to deploy_app instead — credentials are used only to pull, never stored.)

Tools

On a server with deployment jobs enabled, deployment tools return jobId and pollAfterMs promptly. Call get_deployment_job after that delay until the job finishes; the live URL appears in a successful job's result. If a job reports an interrupted failure, inspect list_apps before explicitly deploying again, especially when a release command runs a database migration. CLI up and push poll automatically and print the URL on completion. Older servers retain their existing response behavior.

All three deployment tools accept an optional readinessPath. Set it to an absolute path such as /health when an API app does not return 2xx/3xx at /. The path may be at most 256 characters and cannot include a query or fragment. During a redeploy, omitting it keeps the app's existing readiness path; new apps default to / on the server.

| Tool | What it does | |---|---| | deploy_source | Deploy a local folder — no git, no Docker; uploads it and builds server-side with Nixpacks (the zero-setup path) | | deploy_app | Deploy a Docker image to a project → live HTTPS URL (creates project if new) | | deploy_from_git | Build a git repo with Nixpacks and deploy it (when you already have a repo URL) | | get_deployment_job | Read the status/result of an accepted deployment job; check again after pollAfterMs while pending | | add_database | Provision managed Postgres (auto-injected as DATABASE_URL) | | set_compliance | Generate GDPR imprint + privacy policy + cookie banner → public URLs | | list_apps | List a project's deployments (status + URL) | | delete_app | Stop an app by name | | list_sizes / list_plans | Catalog of machine sizes and billing plans | | usage | Metered compute units + current cost | | whoami | Debug the connection (resolved tenant) |

Configuration

| Env var | Meaning | |---|---| | CONTROL_PLANE_API_KEY | Your API key (shown once at signup). Required against the hosted panel. | | CONTROL_PLANE_URL | Control plane URL. Default https://panel.breezedeploy.dev; point it at your own instance when self-hosting. |

Develop

npm install
npm run typecheck
npm test           # drives the server over an in-memory transport vs a mocked API
npm start          # run the server on stdio (uses CONTROL_PLANE_* env)
npm run build      # compile to dist/ (what the npm package ships)

The MCP registry manifest lives in server.json; publish flow: npm publish (runs typecheck + tests + build), then mcp-publisher publish.