DeployHQ MCP Server

Last updated on 11th November 2025

The DeployHQ MCP Server is a Model Context Protocol (MCP) server that enables AI assistants like Claude Desktop and Claude Code to interact with your DeployHQ deployments. This allows you to manage deployments, check status, view logs, and more using natural language.

What is MCP?

The Model Context Protocol (MCP) is a standard protocol that allows AI assistants to interact with external tools and services. The DeployHQ MCP Server implements this protocol to provide seamless integration between AI assistants and your DeployHQ account.

Features

  • Full DeployHQ Integration: Access projects, servers, and deployments through AI
  • Easy Installation: Use directly with npx - no installation required
  • Secure: Credentials via environment variables, never stored
  • Works with Claude Desktop and Claude Code: Compatible with both MCP clients

Available Tools

The MCP server provides 7 tools that AI assistants can use:

list_projects

List all projects in your DeployHQ account.

Returns: Array of projects with repository information and deployment status.

get_project

Get detailed information about a specific project.

Parameters: - permalink (string): Project permalink or identifier

list_servers

List all servers configured for a project.

Parameters: - project (string): Project permalink

list_deployments

List deployments for a project with pagination support.

Parameters: - project (string): Project permalink - page (number, optional): Page number for pagination - server_uuid (string, optional): Filter by server UUID

get_deployment

Get detailed information about a specific deployment.

Parameters: - project (string): Project permalink - uuid (string): Deployment UUID

getdeploymentlog

Get the deployment log for a specific deployment. Useful for debugging failed deployments.

Parameters: - project (string): Project permalink - uuid (string): Deployment UUID

Returns: Complete deployment log as text

create_deployment

Create a new deployment for a project.

Parameters: - project (string): Project permalink - parent_identifier (string): Server or server group UUID - start_revision (string): Starting commit hash - end_revision (string): Ending commit hash - branch (string, optional): Branch to deploy from - mode (string, optional): "queue" or "preview" - copy_config_files (boolean, optional): Copy config files - run_build_commands (boolean, optional): Run build commands - use_build_cache (boolean, optional): Use build cache - use_latest (string, optional): Use latest deployed commit as start

Installation and Configuration

Prerequisites

  • Node.js 18 or higher
  • DeployHQ account with API access
  • Claude Desktop or Claude Code installed

Getting Your Credentials

You'll need three pieces of information:

  1. Email: Your DeployHQ login email
  2. API Key: Found in Settings > Security in your DeployHQ account
  3. Account Name: Your account name from the URL (https://ACCOUNT.deployhq.com)

Configuration for Claude Desktop

Edit your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the following configuration:

{
  "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"
      }
    }
  }
}

After adding the configuration, restart Claude Desktop.

Configuration for Claude Code

Add the configuration to your .claude.json file in your project directory:

{
  "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"
      }
    }
  }
}

Optional Configuration

You can add an optional LOG_LEVEL environment variable to control logging verbosity:

{
  "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",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Available log levels: - ERROR: Only show errors - INFO: Show info and errors (default) - DEBUG: Show all logs including detailed API calls

Usage Examples

Once configured, you can interact with DeployHQ using natural language. Here are some common examples:

Check Deployment Status

You: What's the status of my latest deployment for my-app?

The AI will use the list_deployments and get_deployment tools to show you the current deployment status.

List Your Projects

You: List all my DeployHQ projects

The AI will use the list_projects tool to show all your projects with their current status.

View Server Configuration

You: Show me the servers configured for my-app

The AI will use the list_servers tool to display all servers for the specified project.

Debug Failed Deployment

You: Why did the last deployment fail for my-app?

The AI will use list_deployments to find the failed deployment, then get_deployment_log to retrieve and analyze the deployment log.

Create a New Deployment

You: Deploy the latest changes to production for my-app

The AI will: 1. Use list_projects to find your project 2. Use list_servers to find the production server 3. Use list_deployments to get the last deployed revision 4. Use create_deployment to queue the deployment 5. Use get_deployment to show the deployment status

Monitor Deployment Progress

You: Show me the deployment log for the current deployment of my-app

The AI will use list_deployments to find the active deployment and get_deployment_log to show you the real-time progress.

Troubleshooting

Server Won't Start

Problem: Server exits immediately after starting

Solutions: - Check that all required environment variables are set correctly - Verify Node.js version is 18 or higher: node --version - Check Claude Desktop/Code logs for error messages - Try setting LOG_LEVEL=DEBUG for more details

Log locations: - macOS: ~/Library/Logs/Claude/ - Windows: %APPDATA%\Claude\logs\

Authentication Errors

Problem: "Authentication failed" or 401/403 errors

Solutions: - Verify your email and API key are correct - Check that your API key is active in Settings > Security - Ensure your account has API access enabled - Try logging into DeployHQ web interface with the same credentials

Project Not Found

Problem: "Project not found" or 404 errors

Solutions: - Use the list_projects tool to see the exact permalink format - Project permalinks are case-sensitive - Verify you have access to the project in DeployHQ

Deployment Fails

Problem: Deployment created but fails immediately

Solutions: - Use get_deployment_log to see detailed error messages - Verify the server UUID is correct with list_servers - Check that start and end revisions exist in your repository - Ensure the server has correct deploy keys configured in DeployHQ

Connection Timeouts

Problem: "Request timeout" errors

Solutions: - Check your internet connection - Verify DeployHQ is accessible: curl https://your-account.deployhq.com - Large deployment lists may take time - the tool supports pagination - Try again in a moment if DeployHQ is experiencing issues

Frequently Asked Questions

What is the difference between the MCP Server and the API?

The MCP Server is designed for AI assistants to interact with DeployHQ using natural language, while the API is for direct programmatic access. The MCP Server uses the DeployHQ API under the hood, but provides a conversational interface through AI assistants.

Do I need to install anything besides npx?

No. The npx command will automatically download and run the latest version of the MCP server. You just need Node.js 18 or higher installed on your system.

Can I use the MCP Server with multiple DeployHQ accounts?

Yes. You can configure multiple MCP servers in your configuration file, each with different credentials. Simply use different names for each server configuration (e.g., "deployhq-production", "deployhq-staging").

Example: json { "mcpServers": { "deployhq-production": { "command": "npx", "args": ["-y", "deployhq-mcp-server"], "env": { "DEPLOYHQ_EMAIL": "prod@example.com", "DEPLOYHQ_API_KEY": "prod-key", "DEPLOYHQ_ACCOUNT": "production-account" } }, "deployhq-staging": { "command": "npx", "args": ["-y", "deployhq-mcp-server"], "env": { "DEPLOYHQ_EMAIL": "staging@example.com", "DEPLOYHQ_API_KEY": "staging-key", "DEPLOYHQ_ACCOUNT": "staging-account" } } } }

Is my API key stored anywhere?

No. Your credentials are passed as environment variables to the MCP server process and are never written to disk or sent anywhere except directly to the DeployHQ API over HTTPS.

Can the AI assistant trigger deployments without asking me?

The AI assistant will typically ask for confirmation before creating a deployment. However, the exact behavior depends on how you phrase your request. For safety, always review what the AI plans to do before confirming.

What permissions does the API key need?

The API key should have the same permissions as your DeployHQ user account. To create deployments, your account needs deployment permissions for the relevant projects. To view deployment logs, you need read access to the projects.

Does the MCP Server work offline?

No. The MCP Server requires an internet connection to communicate with the DeployHQ API. All operations are performed in real-time against your DeployHQ account.

How do I update to the latest version?

Since the MCP Server is run via npx with the -y flag, it automatically uses the latest published version from npm. To force a fresh download, you can clear the npx cache:

npx clear-npx-cache

Or specify a specific version:

{
  "mcpServers": {
    "deployhq": {
      "command": "npx",
      "args": ["-y", "deployhq-mcp-server@1.0.0"]
    }
  }
}

Can I use this with other AI assistants besides Claude?

The MCP Server implements the standard Model Context Protocol, so it should work with any MCP-compatible AI assistant. However, it has been primarily tested with Claude Desktop and Claude Code.

What happens if I have a slow internet connection?

The MCP Server includes timeout handling, but operations may be slower on slow connections. For large deployment lists, consider using pagination by asking the AI to show results in smaller batches.

Can I see what API calls are being made?

Yes. Set the LOG_LEVEL environment variable to DEBUG in your configuration. This will output detailed information about all API calls, including URLs and response data, to the Claude Desktop/Code logs.

You can ask the AI to "list all my DeployHQ projects" and it will show you the permalinks for all your projects. Alternatively, the permalink is visible in the URL when you view a project in the DeployHQ web interface: https://your-account.deployhq.com/projects/YOUR-PERMALINK

Can I deploy to multiple servers at once?

Yes. You can create server groups in DeployHQ and use the group UUID as the parent_identifier when creating a deployment. Ask the AI to "show me the servers for my-app" to see both individual servers and server groups.

What should I do if the AI doesn't understand my request?

Try being more specific with project names and actions. For example, instead of "deploy my app", try "create a deployment for my-app project to the production server with the latest changes". You can also ask the AI to "list my projects" first to get the exact project names.

Security

  • Environment Variables: Credentials are passed via environment variables and never stored
  • Local Execution: When using npx, credentials stay local to your machine
  • No Telemetry: No data is sent anywhere except directly to DeployHQ API
  • HTTPS Only: All API communication uses HTTPS

Additional Resources