DeployHQ MCP Server

A Model Context Protocol (MCP) server for DeployHQ that enables AI assistants like Claude Desktop and Claude Code to interact with your DeployHQ deployments.

🚀 Features

• Full DeployHQ API Integration: Access projects, servers, and deployments
• Easy Installation: Use directly with npx - no installation required
• Works with Claude Desktop & Claude Code: stdio transport for both MCP clients
• Secure: Credentials via environment variables, never stored
• Type-Safe: Built with TypeScript and Zod validation
• Multiple Transports: stdio (primary), SSE, and HTTP (optional for hosting)
• Production-Ready: Comprehensive error handling and logging

📋 Available Tools

The MCP server provides 7 tools for AI assistants:

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

get_deployment_log

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

🚀 Quick Start

Easy Installation with Claude Code

The fastest way to install for Claude Code:

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

Replace your-email@example.com, your-api-key, and your-account with your actual DeployHQ credentials.

Manual Configuration (Works for Both Claude Desktop and Claude Code)

The same configuration works for both clients. Copy from docs/claude-config.json and add your credentials.

For Claude Desktop:

Edit your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Then restart Claude Desktop.

For Claude Code:

Add to your .claude.json file in your project directory.

Configuration:

{
  "mcpServers": {
    "deployhq": {
      "command": "npx",
      "args": ["-y", "deployhq-mcp-server"],
      "env": {
        "DEPLOYHQ_EMAIL": "your-email@example.com",
        "DEPLOYHQ_API_KEY": "your-password",
        "DEPLOYHQ_ACCOUNT": "your-account-name"
        // Optional: "LOG_LEVEL": "INFO"  (ERROR, INFO, or DEBUG)
      }
    }
  }
}

Note: Only the 3 DeployHQ credentials are required. LOG_LEVEL is optional and defaults to INFO.

Start Using

Once configured, you can ask Claude to interact with DeployHQ:

• "List all my DeployHQ projects"
• "Show me the servers for project X"
• "Get the latest deployment status for project Y"
• "Create a new deployment for project Z"
• "Show me the deployment log for the latest deployment"

💡 Common Usage Examples

Check Deployment Status

User: What's the status of my latest deployment for my-app?
Claude: [Uses list_deployments → get_deployment → shows status]

Debug Failed Deployment

User: Why did the last deployment fail for my-app?
Claude: [Uses list_deployments → get_deployment_log → analyzes log]

Deploy Latest Changes

User: Deploy the latest changes to production for my-app
Claude: [Uses list_servers → list_deployments → create_deployment with use_latest]

Complete Workflow Example

User: I want to deploy my-app to production with the latest changes

Claude will:
1. Use list_projects to find "my-app"
2. Use list_servers to find production server UUID
3. Use list_deployments with use_latest to get last revision
4. Use create_deployment to queue deployment
5. Use get_deployment to show status
6. Use get_deployment_log if anything fails

🔧 Configuration Options

Environment Variables

Required

• DEPLOYHQ_EMAIL: Your DeployHQ login email
• DEPLOYHQ_API_KEY: Your DeployHQ password/API key
• DEPLOYHQ_ACCOUNT: Your DeployHQ account name (from URL: https://ACCOUNT.deployhq.com)

Optional

• LOG_LEVEL: Controls log verbosity - ERROR, INFO, or DEBUG (default: INFO)
• NODE_ENV: Environment mode - production or development

Log Levels

Control verbosity with the LOG_LEVEL environment variable:

• ERROR: Only show errors
• INFO: Show info and errors (default)
• DEBUG: Show all logs including detailed API calls

Example:

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

🐛 Troubleshooting

Server Won't Start

Problem: Server exits immediately after starting

Solutions:

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

Authentication Errors

Problem: "Authentication failed" or 401/403 errors

Solutions:

• Verify your email and API key are correct
• Check that your API key hasn't expired
• Ensure your account has API access enabled
• Try logging into DeployHQ web interface with same credentials

Project Not Found

Problem: "Project not found" or 404 errors

Solutions:

• Use list_projects to see exact permalink format
• Project permalinks are case-sensitive
• Check that you have access to the project in DeployHQ

Deployment Creation Blocked

Problem: "Server is running in read-only mode" error when trying to create deployments

Solution:

• Read-only mode is disabled by default, but you may have enabled it
• To disable read-only mode, set DEPLOYHQ_READ_ONLY=false in your environment variables
• Or use the --read-only=false CLI flag
• See the Security section for detailed instructions on read-only mode

Deployment Fails

Problem: Deployment created but fails immediately

Solutions:

• Use get_deployment_log to see detailed error logs
• Verify server UUID is correct with list_servers
• Check that start and end revisions exist in repository
• Ensure server has correct deploy keys configured

Connection Timeouts

Problem: "Request timeout" errors

Solutions:

• Check your internet connection
• Verify DeployHQ API is accessible: curl https://YOUR_ACCOUNT.deployhq.com
• Large deployment lists may take time - use pagination
• Try again in a moment if DeployHQ is experiencing issues

Logs Not Showing

Problem: Not seeing any log output

Solutions:

• Logs go to stderr, not stdout (for stdio transport)
• Check Claude Desktop/Code logs location:
  • macOS: ~/Library/Logs/Claude/
  • Windows: %APPDATA%\Claude\logs\
• Set LOG_LEVEL=DEBUG for verbose output
• For hosted mode, check Digital Ocean logs

Getting Your DeployHQ Credentials

1. Username: Your DeployHQ login email
2. Password: Your DeployHQ password
3. Account: Your DeployHQ account name (visible in the URL: https://ACCOUNT.deployhq.com)

🏗️ Architecture

┌─────────────────┐                    ┌─────────────┐
│  Claude Desktop │    stdio/JSON-RPC  │  DeployHQ   │
│  or Claude Code │◄──────────────────►│  API        │
│                 │    (via npx)       │             │
│  Environment    │                    │             │
│  Variables ─────┼───────────────────►│ Basic Auth  │
└─────────────────┘                    └─────────────┘

• Claude Desktop/Code: MCP clients that spawn the server via npx
• MCP Server: Reads credentials from environment variables, communicates via stdio
• DeployHQ API: REST API with HTTP Basic Authentication

📦 Prerequisites

• Node.js 18+ (Node 20+ recommended)
• DeployHQ account with API access

Note: The server uses node-fetch for HTTP requests. Node 18+ is required for development tools (ESLint, Vitest).

🔧

---