Deployhq Mcp Server

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 18 tools for AI assistants:

| Tool | Description | Parameters | |------|-------------|------------| | list_projects | List all projects | None | | get_project | Get project details | permalink | | list_servers | List project servers | project | | list_deployments | List deployments with pagination | project, page?, server_uuid? | | get_deployment | Get deployment details | project, uuid | | get_deployment_log | Get deployment log output | project, uuid | | create_deployment | Create new deployment | project, parent_identifier, start_revision, end_revision, + optional params | | list_ssh_keys | List all SSH public keys | None | | create_ssh_key | Create a new SSH key pair | title, key_type? | | list_global_environment_variables | List all global environment variables | None | | create_global_environment_variable | Create a global environment variable | name, value, locked?, build_pipeline? | | update_global_environment_variable | Update a global environment variable | id, name?, value?, locked?, build_pipeline? | | delete_global_environment_variable | Delete a global environment variable | id | | list_global_config_files | List all global config file templates | None | | get_global_config_file | Get a global config file with body | id | | create_global_config_file | Create a global config file template | path, body, description?, build? | | update_global_config_file | Update a global config file template | id, path?, body?, description?, build? | | delete_global_config_file | Delete a global config file template | id |

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

list_ssh_keys

List all SSH public keys for the account.

Returns: Array of SSH keys with public keys, fingerprints, and key types. Never returns private keys.

create_ssh_key

Create a new SSH key pair for the account.

Parameters:

• title (string): Title for the SSH key
• key_type (string, optional): Key type — ED25519 (default) or RSA

list_global_environment_variables

List all global (account-level) environment variables.

Returns: Array of environment variables with names, masked values, and settings.

create_global_environment_variable

Create a new global environment variable available across all projects.

Parameters:

• name (string): Variable name
• value (string): Variable value
• locked (boolean, optional): Lock the variable to prevent changes
• build_pipeline (boolean, optional): Make available in build pipeline

update_global_environment_variable

Update an existing global environment variable.

Parameters:

• id (string): Environment variable identifier
• name (string, optional): Variable name
• value (string, optional): Variable value
• locked (boolean, optional): Lock status
• build_pipeline (boolean, optional): Build pipeline availability

delete_global_environment_variable

Delete a global environment variable. This action is irreversible.

Parameters:

• id (string): Environment variable identifier

list_global_config_files

List all global (account-level) config file templates.

Returns: Array of config files with paths, descriptions, and settings.

get_global_config_file

Get a specific global config file template including its body content.

Parameters:

• id (string): Config file identifier (UUID)

create_global_config_file

Create a new global config file template.

Parameters:

• path (string): File path (e.g. config/database.yml)
• body (string): File contents
• description (string, optional): Description of the config file
• build (boolean, optional): Use with build pipeline

update_global_config_file

Update an existing global config file template.

Parameters:

• id (string): Config file identifier (UUID)
• path (string, optional): File path
• body (string, optional): File contents
• description (string, optional): Description
• build (boolean, optional): Build pipeline flag

delete_global_config_file

Delete a global config file template. This action is irreversible.

Parameters:

• id (string): Config file identifier (UUID)

🚀 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, then exit and restart your Claude session (type exit or Ctrl+D, then run claude).

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"
• "List my global environment variables"
• "Create a global config file template for database.yml"
• "Show my SSH keys"

💡 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
• DEPLOYHQ_READ_ONLY: Set to true to block all mutating operations (default: false)

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](#-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 (available on all paid plans)

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

🔧 Local Development

1. Clone the repository

git clone https://github.com/your-username/deployhq-mcp-server.git
cd deployhq-mcp-server

2. Install dependencies

npm install

3. Run tests

npm test              # Run tests once
npm run test:watch    # Run tests in watch mode
npm run test:coverage # Run tests with coverage report
npm run test:ui       # Run tests with UI

4. Build the project

npm run build

5. Test stdio transport locally

# Build first
npm run build

# Test with environment variables
DEPLOYHQ_EMAIL="your-email@example.com" \
DEPLOYHQ_API_KEY="your-api-key" \
DEPLOYHQ_ACCOUNT="your-account" \
node dist/stdio.js

The server will start in stdio mode and wait for JSON-RPC messages on stdin.

6. Test with Claude Code

Configure your local .claude.json to use the built version:

{
  "mcpServers": {
    "deployhq": {
      "command": "node",
      "args": ["/path/to/deployhq-mcp-server/dist/stdio.js"],
      "env": {
        "DEPLOYHQ_EMAIL": "your-email@example.com",
        "DEPLOYHQ_API_KEY": "your-password",
        "DEPLOYHQ_ACCOUNT": "your-account-name"
      }
    }
  }
}

🧪 Testing

The project includes a comprehensive test suite using Vitest:

Test Coverage:

• ✅ Tool Schema Validation - All 18 MCP tool schemas with valid/invalid inputs
• ✅ API Client Methods - All DeployHQ API methods with mocked responses
• ✅ Error Handling - Authentication, validation, and network errors
• ✅ MCP Server Factory - Server creation and configuration

Running Tests:

npm test              # Run all tests
npm run test:watch    # Watch mode for development
npm run test:coverage # Generate coverage report
npm run test:ui       # Interactive UI for debugging

Test Stats:

• 216 tests across 10 test suites
• Covers tools, api-client, and mcp-server modules
• Uses mocked fetch for isolated unit testing

🔒 Security

Read-Only Mode (Optional)

By default, the MCP server allows all operations, including creating deployments.

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: deployhq
• Source: deployhq/deployhq-mcp-server
• License: MIT
• Homepage: https://deployhq.com/

Install and usage instructions live in the source repository linked above.