Overview

The DeployHQ MCP Server is a lightweight Model Context Protocol (MCP) adapter that exposes DeployHQ deployment functionality as tools that an AI assistant or agent can call. It runs as an HTTP service and advertises a set of MCP-compatible tools so LLM-powered agents can list projects and servers, inspect deployments and logs, and create new deployments programmatically.

Because it can be launched with npx (no global install required), the server is convenient for quickly enabling AI-driven deployment workflows in local or transient environments. Typical uses include integrating deployment actions into an assistant, automating routine release tasks, and giving observability into recent deployment history to an agent without granting full API access to humans.

Features

Run an MCP-compatible server with no install via npx
Exposes DeployHQ operations as callable tools for LLM agents
List projects and servers
View recent deployments and their statuses
Retrieve deployment logs for troubleshooting
Initiate new deployments (create deployments) from an agent
Configurable via environment variables or command flags
Lightweight and designed for transient/dev usage

Installation / Configuration

Run directly with npx (no global install):

# Run on the default port
npx deployhq-mcp-server

# Specify a port
npx deployhq-mcp-server --port 3000

# Provide API token as an env var inline
DEPLOYHQ_API_TOKEN=your_token_here npx deployhq-mcp-server --port 3000

Alternatively, clone and run locally:

git clone https://github.com/deployhq/deployhq-mcp-server.git
cd deployhq-mcp-server
npm install
npm start

Common configuration options (supported via environment variables or CLI flags):

DEPLOYHQ_API_TOKEN (required) — DeployHQ API token used to authenticate requests
PORT / –port — port to bind the MCP server (default: 3000)
HOST / –host — optional host binding

A simple .env example:

DEPLOYHQ_API_TOKEN=xxxxxx-your-token-xxxxxx
PORT=3000

Start with dotenv-aware CLI or export variables in your shell:

export DEPLOYHQ_API_TOKEN=xxxx
npx deployhq-mcp-server

Available Tools

The server exposes a set of MCP-compatible tools (function-like actions) that an agent can call. Below is a concise summary of each tool, the typical input shape, and expected outputs.

Tool name	Purpose	Input (example)	Output
listProjects	List DeployHQ projects	{ } or filter options	Array of project objects (id, name, slug)
listServers	List servers for a project	{ projectId }	Array of server objects (id, name, environment)
listDeployments	Show recent deployments	{ projectId, limit, status }	Array of deployment records (id, ref, status, startedAt)
getDeploymentLogs	Fetch logs for a deployment	{ deploymentId }	String or structured log events
createDeployment	Create a new deployment	{ projectId, targetServerIds[], ref, options }	Created deployment object (id, status, link)

Note: The server advertises these tools via MCP so compatible agent frameworks can discover them and route calls automatically.

Example tool-call payload (createDeployment):

{
  "projectId": 12345,
  "targetServerIds": [987, 988],
  "ref": "main",
  "options": {
    "manual": false,
    "deployMessage": "Automated deploy via MCP"
  }
}

Use Cases

Automating routine releases: configure an assistant to run regression checks, then call createDeployment to push a tested branch to staging or production.
Observability for chat-based troubleshooting: a support bot can run listDeployments and getDeploymentLogs to surface recent deploy failures during incident triage.
Controlled self-service: non-admin developers can interact via an approved assistant to trigger deployments without direct access to the DeployHQ UI or API tokens.
CI/CD augmentation: a pipeline can invoke the MCP server (or an agent that uses it) to orchestrate multi-server deployments, report statuses to chat, or annotate issues with deployment details.

Example workflow — from a conversational agent:

User: “Deploy branch fix/login to staging.”
Agent: call listProjects → find project ID.
Agent: call listServers with project ID → choose staging server.
Agent: call createDeployment with ref “fix/login” and target server ID.
Agent: poll listDeployments or getDeploymentLogs to report status back to the user.

Notes and Best Practices

Security: treat your DeployHQ API token as a secret. When running the server in production-like environments, restrict network access and rotate tokens regularly.
Permissions: the actions available to the server reflect the permissions of the configured API token. Use scoped tokens where possible.
Local development: using npx is convenient for demos. For long-running or production setups, run from a managed process (systemd, container) and inject secrets via a secrets manager.
Agent safety: implement guardrails in the agent (approval steps, rate limiting) before allowing automated production deployments.

For source, issues and contribution details, see the project repository on GitHub at the provided URL.

DeployHQ MCP Server for AI Deployments via npx