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:

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

🔧 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 7 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:

• 50+ tests across 3 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

---

🌐 Optional: Hosted Deployment

The server can also be deployed as a hosted service with SSE/HTTP transports. This is useful for web integrations or shared team access.

🚀 Deployment to Digital Ocean

Option 1: Using the Dashboard

1. Prepare your repository:

   git add .
   git commit -m "Initial commit"
   git push origin main
   

2. Create a new app:

   • Go to Digital Ocean Apps
   • Click "Create App"
   • Select your GitHub repository
   • Choose the branch (main)

3. Configure the app:

   • Digital Ocean will detect the Dockerfile automatically
   • Or use the .do/app.yaml configuration

4. Set environment variables:

   • Go to App Settings → Environment Variables
   • Add the following as encrypted variables:
     • DEPLOYHQ_EMAIL
     • DEPLOYHQ_API_KEY
     • DEPLOYHQ_ACCOUNT
   • Add these as regular variables:
     • NODE_ENV=production
     • PORT=8080
     • LOG_LEVEL=info

5. Deploy:

   • Click "Next" and "Create Resources"
   • Wait for deployment to complete

6. Configure custom domain (optional):

   • Go to Settings → Domains
   • Add mcp.deployhq.com
   • Update your DNS records as instructed

Option 2: Using doctl CLI

1. Install doctl:

   # macOS
   brew install doctl
   
   # Linux
   cd ~
   wget https://github.com/digitalocean/doctl/releases/download/v1.104.0/doctl-1.104.0-linux-amd64.tar.gz
   tar xf doctl-1.104.0-linux-amd64.tar.gz
   sudo mv doctl /usr/local/bin
   

2. Authenticate:

   doctl auth init
   

3. Update .do/app.yaml:

   • Edit the github.repo field with your repository
   • Review and adjust instance size if needed

4. Create the app:

   doctl apps create --spec .do/app.yaml
   

5. Set environment secrets:

   # Get your app ID
   doctl apps list
   
   # Update environment variables (replace APP_ID)
   doctl apps update APP_ID --spec .do/app.yaml
   

6. View logs:

   doctl apps logs APP_ID --follow
   

🔒 Hosted Security

• Never commit credentials: Use .env for local development (excluded by .gitignore)
• Use Digital Ocean secrets: Store credentials as encrypted environment variables
• HTTPS only: Digital Ocean provides automatic HTTPS
• Minimal permissions: Use a dedicated DeployHQ user with minimum required permissions

📊 Hosted Monitoring

Health Check

The hosted server includes a health check endpoint at /health:

curl https://mcp.deployhq.com/health

Logs

View logs in Digital Ocean:

• Dashboard: Go to your app → Runtime Logs
• CLI: doctl apps logs <APP_ID> --follow

Alerts

Digital Ocean will alert you on:

• Deployment failures
• Domain configuration issues
• Health check failures

🧪 Testing Hosted Server

Test the SSE endpoint:

curl -N http://localhost:8080/sse \
  -H "X-DeployHQ-Email: your-email@example.com" \
  -H "X-DeployHQ-API-Key: your-api-key" \
  -H "X-DeployHQ-Account: your-account"

Test the HTTP transport endpoint:

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "X-DeployHQ-Email: your-email@example.com" \
  -H "X-DeployHQ-API-Key: your-api-key" \
  -H "X-DeployHQ-Account: your-account" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "params": {},
    "id": 1
  }'

See the hosted deployment documentation for full testing examples.

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

📄 License

MIT License - see LICENSE file for details

🆘 Support

• DeployHQ API Documentation: https://www.deployhq.com/support/api
• MCP Documentation: https://modelcontextprotocol.io
• Issues: https://github.com/deployhq/deployhq-mcp-server/issues

🔗 Related Links

• DeployHQ
• Model Context Protocol
• Digital Ocean App Platform
• Claude Desktop
• Claude Code CLI