deployhq-mcp-server

KO | EN

gitlite — search

#python #hacktoberfest #typescript #llm #machine-learning #nodejs #java #cli #kubernetes #vue #pytorch #mcp #ios #openai

deployhq-mcp-server

(★ 13)

DeployHQ MCP Server

deployhq-mcp-server 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

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

| 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_ssh_keys` | List all SSH public keys | None |
| `create_ssh_key` | Create a new SSH key pair | `title`, `key_type?` |
| `list_global_environment_variables` | List all global environment variables | None |
| `create_global_environment_variable` | Create a global environment variable | `name`, `value`, `locked?`, `build_pipeline?` |
| `update_global_environment_variable` | Update a global environment variable | `id`, `name?`, `value?`, `locked?`, `build_pipeline?` |
| `delete_global_environment_variable` | Delete a global environment variable | `id` |
| `list_global_config_files` | List all global config file templates | None |
| `get_global_config_file` | Get a global config file with body | `id` |
| `create_global_config_file` | Create a global config file template | `path`, `body`, `description?`, `build?` |
| `update_global_config_file` | Update a global config file template | `id`, `path?`, `body?`, `description?`, `build?` |
| `delete_global_config_file` | Delete a global config file template | `id` |

### `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:

```bash
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:**

```json
{
  "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:
```json
{
  "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](#-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** (available on all paid plans)

**Note**: The server uses `node-fetch` for HTTP requests. Node 18+ is required for development tools (ESLint, Vitest).

## 🔧 Local Development

### 1. Clone the repository

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

### 2. Install dependencies

```bash
npm install
```

### 3. Run tests

```bash
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

```bash
npm run build
```

### 5. Test stdio transport locally

```bash
# 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:

```json
{
  "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:**
```bash
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:
```json
{
  "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:
```json
{
  "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**:
   ```bash
   git add .
   git commit -m "Initial commit"
   git push origin main
   ```

2. **Create a new app**:
   - Go to [Digital Ocean Apps](https://cloud.digitalocean.com/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**:
   ```bash
   # 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**:
   ```bash
   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**:
   ```bash
   doctl apps create --spec .do/app.yaml
   ```

5. **Set environment secrets**:
   ```bash
   # 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**:
   ```bash
   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`:

```bash
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:

```bash
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:

```bash
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](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

- **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](https://www.deployhq.com)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [Digital Ocean App Platform](https://www.digitalocean.com/products/app-platform)
- [Claude Desktop](https://claude.ai/desktop)
- [Claude Code CLI](https://github.com/anthropics/claude-code)

deployhq-mcp-server

deployhq-mcp-server 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

deployhq-mcp-server

deployhq-mcp-server 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README