@getbelmo/mcp-server

Model Context Protocol server for Belmo. Connect your AI coding tool to your Belmo account to sign in, manage workspaces, deploy GitHub repositories, and inspect deployment status — all through tool calls.

Install

The MCP server is published as a Node CLI:

npx -y @getbelmo/mcp-server

Claude Desktop

Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "belmo": {
      "command": "npx",
      "args": ["-y", "@getbelmo/mcp-server"]
    }
  }
}

Cursor / Windsurf / other MCP clients

Use the same command + args shape in the client's MCP config.

Sign in

The MCP server stores credentials encrypted at ~/.hostingguru/credentials.json.

Email, Google, or GitHub

In your AI tool, run the auth_login tool. The server opens your browser to the Belmo dashboard sign-in page (dashboard.belmo.io), where you log in the normal way — email/password, Google, or GitHub all work. After you sign in, the dashboard hands the session back to the server's localhost loopback over a single-use, short-lived code, and you're authenticated. Credentials never pass through the AI tool, and the session token never appears in the browser.

If the browser can't open automatically (e.g. a remote/SSH session), the tool also prints the URL so you can open it manually.

If your email is unknown, an account is created automatically — same flow as the dashboard.

Session token (fallback)

If the browser flow can't run at all, run auth_token and paste the value of the token cookie copied from https://dashboard.belmo.io (DevTools → Application → Cookies). Normally you won't need this — auth_login handles email, Google, and GitHub directly.

Sign out

Run auth_logout. The local credentials file is removed and the backend cookie is invalidated.

Tools

| Tool | What it does | | --- | --- | | auth_login | Opens your browser to the dashboard; sign in with email, Google, or GitHub | | auth_signup | Create a new account (just use auth_login — new emails auto-register) | | auth_token | Authenticate with a session token (fallback if the browser flow can't run) | | auth_status | Show authenticated state + selected workspace | | auth_logout | Sign out locally and on the backend | | list_workspaces / select_workspace / create_workspace | Workspace selection and creation | | list_projects / create_project | Project management | | deploy / list_deployments / get_deployment / update_deployment | Create, inspect, and edit deployments | | redeploy / rollback_deployment / stop_deployment / start_deployment | Deployment lifecycle | | get_logs / list_builds / get_build_logs | Logs and build history | | list_env_vars / set_env_vars / delete_env_var | Environment variables | | connect_github / list_repositories / list_branches | GitHub integration | | attach_domain / verify_domain | Custom domains | | get_subscription | Billing status | | setup_gtm_server / list_gtm_servers / get_gtm_server | GTM server-side containers | | redeploy_gtm_server / update_gtm_container_config / delete_gtm_server | GTM lifecycle | | project_link / project_status / env_pull / logs_fetch | Link a local repo to a service |

Security

• All traffic to the API uses HTTPS to backend.belmo.io.
• The session JWT is sent via Cookie: token=… (matches the dashboard's cookie-only auth).
• Local sign-in helper binds to 127.0.0.1 only on an ephemeral port and shuts down after 5 minutes or after first use.
• A random per-session nonce binds the /submit POST to the served login page, so other local processes can't hijack the credential submission.
• Credentials at rest are AES-256-GCM encrypted with a key derived from hostname + username + homedir.

Development

This repo is standalone — no monorepo tooling required.

npm install      # esbuild + typescript (dev), plus the 3 runtime deps
npm run typecheck # tsc --noEmit
npm run build     # bundles src/main.ts -> ./main.cjs (deps stay external)
node main.cjs     # run the built server over stdio

npm run build produces a single-file CJS entry with a node shebang; the three runtime dependencies are left external and installed by npm when users run the package. Publishing is covered in PUBLISH.md.

License

MIT — see LICENSE.