**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](https://www.deployhq.com/support/hosted-mcp-server).
- The **[DeployHQ CLI](https://www.deployhq.com/support/cli) (`dhq`)** is the recommended way to run deployments, rollbacks and log checks, and to automate them. See [AI agents and the CLI](https://www.deployhq.com/agents).

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](https://modelcontextprotocol.io) (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.

| Tool | What it does |
| --- | --- |
| `list_projects`, `get_project` | List your projects, or show one (by permalink). |
| `list_servers` | List the servers of a project. |
| `list_deployments` | List a project's deployments, with optional `page` and `server_uuid` filters. |
| `get_deployment`, `get_deployment_log` | Show one deployment, or its full log (useful for failed deployments). |
| `create_deployment` | Queue or preview a deployment: `project`, `parent_identifier` (server or server group), `start_revision` and `end_revision`, plus optional `branch`, `mode`, `copy_config_files`, `run_build_commands`, `use_build_cache` and `use_latest`. |

The package does not manage SSH keys, environment variables or configuration files. Use the DeployHQ web interface, the [API](https://www.deployhq.com/support/api) or the [CLI](https://www.deployhq.com/support/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:

```json
{
  "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:

```bash
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](https://code.claude.com/docs/en/mcp) 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](https://www.deployhq.com/support/hosted-mcp-server) if you want an assistant to look at your projects, servers, deployments and deployment logs, and the [CLI](https://www.deployhq.com/support/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](https://www.npmjs.com/package/deployhq-mcp-server) and [GitHub repository](https://github.com/deployhq/deployhq-mcp-server) (report issues there)
- [The hosted DeployHQ MCP server](https://www.deployhq.com/mcp)
- [The DeployHQ API](https://www.deployhq.com/support/api) and [The DeployHQ CLI](https://www.deployhq.com/support/cli)
