DeployHQ MCP Server (local package)

For new setups we recommend the hosted DeployHQ MCP server or the DeployHQ CLI.

• The hosted MCP server gives an assistant read-only access to your accounts, projects, servers and deployment status. There is nothing to install: add https://mcp.deployhq.com/mcp to Claude.ai, ChatGPT, Claude Code or another assistant and sign in. It can also read deployment logs, with recognisable credentials replaced with [REDACTED]. It cannot deploy or change configuration. See Connect Claude, ChatGPT and other AI assistants to DeployHQ.
• The DeployHQ CLI (dhq) is the recommended way to run deployments, rollbacks and log checks, and to automate them. See AI agents and the CLI.

This page covers the DeployHQ MCP Server package (deployhq-mcp-server on npm), which runs on your own computer with your API key. It is still supported for now, and it works as described below.

The package is a Model Context Protocol (MCP) server. It lets assistants such as Claude Desktop and Claude Code check deployments, read logs and create deployments in plain language, using the DeployHQ API with your own credentials.

Available tools

The current release, deployhq-mcp-server 1.2.2, provides seven tools. The assistant chooses which to use from what you ask.

The package does not manage SSH keys, environment variables or configuration files. Use the DeployHQ web interface, the API or the CLI for those.

Installation and Configuration

Prerequisites

• Node.js 18 or higher
• A DeployHQ account with API access
• Claude Desktop, Claude Code or another MCP-compatible assistant

Getting Your Credentials

You need all three of these. The package does not start without them.

1. DEPLOYHQ_EMAIL: your DeployHQ login email.
2. DEPLOYHQ_API_KEY: your API key, in Settings > Developers in your DeployHQ account.
3. DEPLOYHQ_ACCOUNT: the account name in your URL (https://ACCOUNT.deployhq.com).

Configuration for Claude Desktop

Edit the Claude Desktop configuration file (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json) and add:

{
  "mcpServers": {
    "deployhq": {
      "command": "npx",
      "args": ["-y", "deployhq-mcp-server"],
      "env": {
        "DEPLOYHQ_EMAIL": "your-email@example.com",
        "DEPLOYHQ_API_KEY": "your-api-key",
        "DEPLOYHQ_ACCOUNT": "your-account-name"
      }
    }
  }
}

Restart Claude Desktop afterwards.

Configuration for Claude Code

The simplest way is the claude mcp add command. This stores the server in ~/.claude.json, so it is available in all your projects:

claude mcp add --transport stdio --scope user \
  --env DEPLOYHQ_EMAIL=your-email@example.com \
  --env DEPLOYHQ_API_KEY=your-api-key \
  --env DEPLOYHQ_ACCOUNT=your-account-name \
  deployhq -- npx -y deployhq-mcp-server

Claude Code keeps MCP server settings in two places: ~/.claude.json in your home directory (for the local and user scopes) and a .mcp.json file in the project root (for the project scope, which is meant to be shared through version control). There is no project-level .claude.json for MCP servers. If you do add the same mcpServers block shown for Claude Desktop to a project's .mcp.json, do not commit it with your API key in it. Prefer the user scope above. See Claude Code's MCP documentation for details.

Optional settings

Add "LOG_LEVEL" to env to control logging: ERROR (errors only), INFO (default) or DEBUG (everything, including each API call).

To stop an assistant creating deployments through the package, set "DEPLOYHQ_READ_ONLY": "true" in env, or add --read-only to args. The other tools keep working. Read-only mode is off by default.

Check that it works

Restart your assistant, then ask: "List my DeployHQ projects." The assistant should call list_projects and show your projects. In Claude Code you can also run /mcp and check that deployhq is listed as connected. If it is not, see Troubleshooting below.

Examples

Once configured, ask in plain language:

• "What's the status of my latest deployment for my-app?" The assistant uses list_deployments and get_deployment.
• "Why did the last deployment fail for my-app?" It finds the failed deployment, then reads its log with get_deployment_log.
• "Deploy the latest changes to production for my-app." It finds the project and the production server, looks up the last deployed revision, then queues the deployment with create_deployment and shows its status.

Troubleshooting

• The server won't start. Check that all three environment variables are set and that node --version is 18 or higher. Set LOG_LEVEL=DEBUG and read the Claude logs (macOS: ~/Library/Logs/Claude/, Windows: %APPDATA%\Claude\logs\).
• Authentication errors (401 or 403). Check your email and API key, that the key is active in Settings > Developers, and that the account has API access. Try signing in to the DeployHQ web interface with the same email.
• Project not found. Ask the assistant to list your projects to see the exact permalink. Permalinks are case-sensitive, and you need access to the project in DeployHQ.
• A deployment fails straight away. Read its log with get_deployment_log, check the server UUID with list_servers, check that both revisions exist in the repository, and check that the server's deploy key is set up in DeployHQ.
• "Server is running in read-only mode". DEPLOYHQ_READ_ONLY is set to true or --read-only is in args. Remove it to allow create_deployment.
• Timeouts. Check your connection and that your DeployHQ account is reachable. Long deployment lists can be slow; the tool supports pages.

Frequently Asked Questions

Should I use this package, the hosted server or the CLI?

For new setups, use the hosted server if you want an assistant to look at your projects, servers, deployments and deployment logs, and the CLI for deployments, rollbacks and automation. This package is still supported for now. It is the option that lets an assistant create deployments through MCP, so check what the assistant plans to do before you confirm.

Is my API key stored anywhere?

The package itself does not save it anywhere. But it only receives the key from the environment your assistant gives it, and that usually means the key is in a configuration file on your computer, such as claude_desktop_config.json, ~/.claude.json or ~/.codex/config.toml. Those files hold the key as plain text on disk. Keep them private to your user account, never commit them to version control, and create a new key in Settings > Developers if one is ever exposed.

What data goes where?

Your assistant starts the package on your computer and talks to it over standard input and output (stdio), so that traffic does not cross the network. The package then sends requests to the DeployHQ API over HTTPS. The results of each tool call, such as project names, deployment details and deployment logs, are passed back to your assistant and shared with the company that provides it, so use assistants you trust with that information.

Can the assistant deploy without asking me?

Assistants usually ask for confirmation before creating a deployment, but this depends on the assistant and how you phrase the request. Always review what it plans to do, or turn on read-only mode (see Optional settings).

What permissions does the API key need?

The same as your DeployHQ user. To create deployments you need deployment permission on the project, and to read logs you need read access to it.

Can I use more than one DeployHQ account?

Yes. Add the configuration block again under a different name, for example deployhq-production and deployhq-staging, each with its own credentials.

How do I update it?

npx -y uses the latest published version. To force a fresh download, run npx clear-npx-cache, or pin a version, for example "deployhq-mcp-server@1.2.2" in args.

Does it work with other assistants?

It follows the standard Model Context Protocol, so it should work with any assistant that supports MCP over stdio, but it has mainly been tested with Claude Desktop and Claude Code.

Can I deploy to several servers at once?

Yes. Create a server group in DeployHQ and use the group's UUID as parent_identifier.

Security

• You supply your credentials as environment variables. The package does not write them anywhere itself, but the assistant's configuration file that holds them is stored on your disk (see the FAQ above).
• The package runs on your computer and talks to your assistant over stdio.
• It sends requests only to your DeployHQ account's API (https://ACCOUNT.deployhq.com), over HTTPS.
• It sends no telemetry.
• What a tool returns is shared with your assistant and its provider.

Additional resources

• npm package and GitHub repository (report issues there)
• The hosted DeployHQ MCP server
• The DeployHQ API and The DeployHQ CLI