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:

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 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 serv