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 [email protected] --env DEPLOYHQ_API_KEY=your-api-key --env DEPLOYHQ_ACCOUNT=your-account -- npx -y deployhq-mcp-server

Replace [email protected], 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": "[email protected]",
        "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": "[email protected]",
        "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

Username: Your DeployHQ login email
Password: Your DeployHQ password
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="[email protected]" \
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": "[email protected]",
        "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": "[email protected]",
        "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": "[email protected]",
        "DEPLOYHQ_API_KEY": "your-api-key",
        "DEPLOYHQ_ACCOUNT": "your-account"
      }
    }
  }
}

Configuration precedence:

CLI flag --read-only (highest priority)
Environment variable DEPLOYHQ_READ_ONLY
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

Prepare your repository:

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

Create a new app:
- Go to Digital Ocean Apps
- Click "Create App"
- Select your GitHub repository
- Choose the branch (main)
Configure the app:
- Digital Ocean will detect the Dockerfile automatically
- Or use the .do/app.yaml configuration
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
Deploy:
- Click "Next" and "Create Resources"
- Wait for deployment to complete
Configure custom domain (optional):
- Go to Settings → Domains
- Add mcp.deployhq.com
- Update your DNS records as instructed

Option 2: Using doctl CLI

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

Authenticate:
```
doctl auth init
```
Update .do/app.yaml:
- Edit the github.repo field with your repository
- Review and adjust instance size if needed
Create the app:
```
doctl apps create --spec .do/app.yaml
```

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

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: [email protected]" \
  -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: [email protected]" \
  -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:

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
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

Name		Name	Last commit message	Last commit date
Latest commit History 43 Commits
.github/workflows		.github/workflows
docs		docs
src		src
.env.example		.env.example
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
RELEASING.md		RELEASING.md
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
server.json		server.json
test-stdio.sh		test-stdio.sh
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

License

deployhq/deployhq-mcp-server

Folders and files

Latest commit

History

Repository files navigation

DeployHQ MCP Server

🚀 Features

📋 Available Tools

list_projects

get_project

list_servers

list_deployments

get_deployment

get_deployment_log

create_deployment

🚀 Quick Start

Easy Installation with Claude Code

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

Start Using

💡 Common Usage Examples

Check Deployment Status

Debug Failed Deployment

Deploy Latest Changes

Complete Workflow Example

🔧 Configuration Options

Environment Variables

Required

Optional

Log Levels

🐛 Troubleshooting

Server Won't Start

Authentication Errors

Project Not Found

Deployment Creation Blocked

Deployment Fails

Connection Timeouts

Logs Not Showing

Getting Your DeployHQ Credentials

🏗️ Architecture

📦 Prerequisites

🔧 Local Development

1. Clone the repository

2. Install dependencies

3. Run tests

4. Build the project

5. Test stdio transport locally

6. Test with Claude Code

🧪 Testing

🔒 Security

Read-Only Mode (Optional)

Additional Security Notes

🌐 Optional: Hosted Deployment

🚀 Deployment to Digital Ocean

Option 1: Using the Dashboard

Option 2: Using doctl CLI

🔒 Hosted Security

📊 Hosted Monitoring

Health Check

Logs

Alerts

🧪 Testing Hosted Server

📚 Project Structure

🤝 Contributing

For Maintainers

📄 License

🆘 Support

🔗 Related Links

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Contributors 2

`list_projects`

`get_project`

`list_servers`

`list_deployments`

`get_deployment`

`get_deployment_log`

`create_deployment`

Packages