DeployHQ

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

- Full DeployHQ API Integration: Access projects, servers, and deployments
- Easy Installation: Use directly withnpx- 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

The MCP server provides18 toolsfor AI assistants:

List all projects in your DeployHQ account.

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

Get detailed information about a specific project.

- permalink(string): Project permalink or identifier

List all servers configured for a project.

List deployments for a project with pagination support.

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

Get detailed information about a specific deployment.

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

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

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

Returns: Complete deployment log as text

- 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 all SSH public keys for the account.

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

Create a new SSH key pair for the account.

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

List all global (account-level) environment variables.

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

Create a new global environment variable available across all projects.

- 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 an existing global environment variable.

- 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 a global environment variable. This action is irreversible.

- id(string): Environment variable identifier

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

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

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

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

Create a new global config file template.

- 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 an existing global config file template.

- 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 a global config file template. This action is irreversible.

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

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

Replaceyour-email@example.com,your-api-key, andyour-accountwith your actual DeployHQ credentials.

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

The same configuration works for both clients. Copy fromdocs/claude-config.jsonand add your credentials.

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

Add to your.claude.jsonfile in your project directory, then exit and restart your Claude session (typeexitor Ctrl+D, then runclaude).

{ "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_LEVELis optional and defaults toINFO.

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"

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

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

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

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

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

- LOG_LEVEL: Controls log verbosity -ERROR,INFO, orDEBUG(default:INFO)
- NODE_ENV: Environment mode -productionordevelopment
- DEPLOYHQ_READ_ONLY: Set totrueto block all mutating operations (default:false)

Control verbosity with theLOG_LEVELenvironment variable:

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

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

Problem: Server exits immediately after starting

- 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 settingLOG_LEVEL=DEBUGfor more details

Problem: "Authentication failed" or 401/403 errors

- 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

Problem: "Project not found" or 404 errors

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

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

- Read-only mode is disabled by default, but you may have enabled it
- To disable read-only mode, setDEPLOYHQ_READ_ONLY=falsein your environment variables
- Or use the--read-only=falseCLI flag
- See theSecuritysection for detailed instructions on read-only mode

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

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

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

# 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