Labsco
deployhq logo

DeployHQ

★ 13

from 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.

🔥🔥🔥✓ VerifiedPaid serviceAdvanced setup
#email#automation#database#devops#git#maps#security#monitoring

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:

ToolDescriptionParameters
list_projectsList all projectsNone
get_projectGet project detailspermalink
list_serversList project serversproject
list_deploymentsList deployments with paginationproject, page?, server_uuid?
get_deploymentGet deployment detailsproject, uuid
get_deployment_logGet deployment log outputproject, uuid
create_deploymentCreate new deploymentproject, parent_identifier, start_revision, end_revision, + optional params
list_ssh_keysList all SSH public keysNone
create_ssh_keyCreate a new SSH key pairtitle, key_type?
list_global_environment_variablesList all global environment variablesNone
create_global_environment_variableCreate a global environment variablename, value, locked?, build_pipeline?
update_global_environment_variableUpdate a global environment variableid, name?, value?, locked?, build_pipeline?
delete_global_environment_variableDelete a global environment variableid
list_global_config_filesList all global config file templatesNone
get_global_config_fileGet a global config file with bodyid
create_global_config_fileCreate a global config file templatepath, body, description?, build?
update_global_config_fileUpdate a global config file templateid, path?, body?, description?, build?
delete_global_config_fileDelete a global config file templateid

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)

🏗️ 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

🔧 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. This is the recommended configuration for most users.

For users who want additional protection against accidental deployments, the server includes an optional read-only mode that can be enabled to block deployment creation.

Default Behavior (No Configuration Needed):

  • ✅ Deployments are allowed by default
  • ✅ All operations work: list, get, and create deployments
  • ✅ Full functionality out of the box

When you might want to enable read-only mode:

  • You want extra protection against accidental deployments via AI
  • You're connecting to production environments and want an additional safety layer
  • You only need read access to monitor deployments
  • You're still testing the integration and want to be cautious

Important: Read-only mode is completely optional. The server works fully without it.

How to enable read-only mode:

Via environment variable:

{
  "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",
        "DEPLOYHQ_READ_ONLY": "true"
      }
    }
  }
}

Via CLI flag:

{
  "mcpServers": {
    "deployhq": {
      "command": "npx",
      "args": [
        "-y",
        "deployhq-mcp-server",
        "--read-only"
      ],
      "env": {
        "DEPLOYHQ_EMAIL": "your-email@example.com",
        "DEPLOYHQ_API_KEY": "your-api-key",
        "DEPLOYHQ_ACCOUNT": "your-account"
      }
    }
  }
}

Configuration precedence:

  1. CLI flag --read-only (highest priority)
  2. Environment variable DEPLOYHQ_READ_ONLY
  3. Default value: false (deployments allowed)

Additional Security Notes

  • Deployment Logs May Contain Secrets: Deployment logs can include environment variables, API keys, and other sensitive information. Exercise caution when using tools that retrieve logs, especially with third-party AI services.

  • Use Least-Privilege API Keys: Create dedicated API keys with minimum required permissions for MCP access. Consider separate keys for read-only vs. read-write operations.

  • Audit MCP Activity: Monitor MCP usage, especially in production environments. Review logs regularly for unexpected behavior.

  • Environment Variables: Credentials are never stored, only passed via environment variables

  • HTTPS: When using npx, credentials stay local to your machine

  • No Telemetry: No data is sent anywhere except directly to DeployHQ API

📚 Project Structure

deployhq-mcp-server/
├── src/
│   ├── stdio.ts          # stdio transport entrypoint (for Claude Desktop/Code)
│   ├── index.ts          # Express server (for hosted deployment)
│   ├── mcp-server.ts     # Core MCP server factory (shared)
│   ├── tools.ts          # Tool definitions and schemas (shared)
│   ├── api-client.ts     # DeployHQ API client (shared)
│   ├── transports/       # SSE/HTTP handlers (for hosted)
│   └── utils/            # Logging and utilities
├── docs/
│   ├── claude-config.json          # Universal config template (Desktop & Code)
│   ├── USER_GUIDE.md               # User documentation
│   ├── DEPLOYMENT.md               # Hosted deployment guide
│   └── HTTP_TRANSPORT.md           # HTTP transport documentation
├── .do/
│   └── app.yaml          # Digital Ocean configuration (optional)
├── Dockerfile            # Container configuration (optional)
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── STDIO_MIGRATION.md    # stdio migration documentation
└── README.md             # This file

🤝 Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

For Maintainers

See RELEASING.md for instructions on creating releases and publishing to npm.

Privacy Policy

This MCP server does not collect, store, or transmit any user data beyond what is necessary to communicate with the DeployHQ API. Credentials are passed via environment variables and are never logged or persisted.

For DeployHQ's full privacy policy, see: https://www.deployhq.com/privacy

📄 License

MIT License - see LICENSE file for details

🆘 Support