ZenHub MCP Server

An MCP (Model Context Protocol) server that provides full access to the ZenHub GraphQL API.

Features

• Full GraphQL Access: Execute any GraphQL query against the ZenHub API
• Common Operations: Built-in tools for frequent tasks like creating issues, epics, workspaces, and sprints
• Secure Authentication: API key-based authentication for all requests
• Error Handling: Comprehensive error handling and validation

Installation

For Development

npm install
npm run build

Setup API Key

1. Get your ZenHub API key from ZenHub Settings

2. Set the environment variable:

export ZENHUB_API_KEY=your_api_key_here

Or create a `.env` file (copy from `.env.example`):

cp .env.example .env
# Edit .env and add your API key

For Claude Desktop

1. Build the server:

npm install
npm run build

2. Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

{
  "mcpServers": {
    "zenhub": {
      "command": "npx",
      "args": ["zenhub-mcp-server"],
      "env": {
        "ZENHUB_API_KEY": "your_api_key_here"
      }
    }
  }
}

For Cursor

1. Build the server:

npm install
npm run build

2. In Cursor, go to Settings > MCP Servers and add:

{
  "name": "zenhub",
  "command": "node",
  "args": ["/path/to/zenhub-mcp/dist/index.js"],
  "env": {
    "ZENHUB_API_KEY": "zh_",
    "GITHUB_PAT": "github_pat_"
  }
}

Or use the development server:

{
  "name": "zenhub-dev",
  "command": "npm",
  "args": ["run", "dev"],
  "cwd": "/path/to/zenhub-mcp",
  "env": {
    "ZENHUB_API_KEY": "your_api_key_here"
  }
}

Tools

The server provides 54 tools across 10 categories, implementing the most commonly used ZenHub operations:

No API key required in tool calls - Set `ZENHUB_API_KEY` environment variable once and use all tools!

Query Tools (7 tools)

`zenhub_query`

Execute any GraphQL query against the ZenHub API.

• `query` (required): GraphQL query string
• `variables` (optional): Variables for the query

`zenhub_search_issues`

Search for issues in a pipeline.

• `pipeline_id` (required): Pipeline ID to search in
• `query` (optional): Search query for title
• `filters` (optional): Object with filters for labels and assignees

`zenhub_search_issues_in_repository`

Search and filter issues inside repository.

• `repository_id` (required): Repository ID to search in
• `query` (optional): Search query
• `filters` (optional): Filter options

`zenhub_get_workspace_issues`

Get all issues in a workspace (paginated).

• `workspace_id` (required): Workspace ID
• `after` (optional): Cursor for pagination

`zenhub_get_viewer`

Get current ZenHub user information.

`zenhub_get_issue_by_info`

Lookup an issue by repository and issue number.

• `repository_gh_id` (required): GitHub repository ID
• `issue_number` (required): Issue number

`zenhub_get_repositories`

Lookup repositories by their GitHub IDs.

• `repository_gh_ids` (required): Array of GitHub repository IDs

Issue Management (13 tools)

`zenhub_create_issue`

Create a new GitHub issue via ZenHub.

• `title` (required): Issue title
• `repository_id` (required): Repository ID
• `body` (optional): Issue description
• `labels` (optional): Array of label names
• `assignees` (optional): Array of GitHub usernames

`zenhub_close_issues`

Close one or more issues.

• `issue_ids` (required): Array of issue IDs

`zenhub_reopen_issues`

Reopen one or more closed issues.

• `issue_ids` (required): Array of issue IDs
• `pipeline_id` (required): Pipeline ID to move issues to
• `position` (optional): Position in pipeline (START or END)

`zenhub_move_issue`

Move issues to a position in a pipeline.

• `issue_ids` (required): Array of issue IDs
• `pipeline_id` (required): Pipeline ID to move issues to
• `position` (optional): Position in pipeline (0-based)

`zenhub_add_assignees_to_issues`

Add assignees to multiple issues.

• `issue_ids` (required): Array of issue IDs
• `assignees` (required): Array of GitHub usernames

`zenhub_add_labels_to_issues`

Add labels to multiple issues.

• `issue_ids` (required): Array of issue IDs
• `labels` (required): Array of label names

`zenhub_set_estimate`

Set an estimate for an issue.

• `issue_id` (required): Issue ID
• `value` (required): Estimate value

`zenhub_set_multiple_estimates`

Set estimates on multiple issues.

• `estimates` (required): Array of issue ID and estimate value pairs

`zenhub_add_issues_to_epics`

Add issues to epics.

• `issue_ids` (required): Array of issue IDs
• `epic_ids` (required): Array of epic IDs

Epic Management (1 tool)

`zenhub_create_epic`

Create a new epic in ZenHub.

• `title` (required): Epic title
• `repository_id` (required): Repository ID
• `body` (optional): Epic description

Workspace Management (4 tools)

`zenhub_get_user_workspaces`

Get all workspaces accessible to the current user.

• `query` (optional): Search query to filter workspaces
• `first` (optional): Number of workspaces to return (default: 20)

`zenhub_get_user_organizations`

Get all ZenHub organizations accessible to the current user.

• `query` (optional): Search query to filter organizations
• `first` (optional): Number of organizations to return (default: 10)

`zenhub_get_organization_workspaces`

Get all workspaces within a specific ZenHub organization.

• `organization_id` (required): ZenHub organization ID
• `query` (optional): Search query to filter workspaces
• `first` (optional): Number of workspaces to return (default: 20)

`zenhub_create_workspace`

Create a new workspace in ZenHub.

• `name` (required): Workspace name
• `description` (optional): Workspace description
• `organization_id` (required): ZenHub organization ID
• `repository_ids` (required): Array of GitHub repository IDs
• `default_repository_id` (optional): Default repository ID

Sprint Management (2 tools)

`zenhub_create_sprint`

Create a new sprint.

• `name` (required): Sprint name
• `start_date` (required): Start date (ISO format)
• `end_date` (required): End date (ISO format)
• `workspace_id` (required): Workspace ID
• `timezone` (optional): Timezone identifier
• `settings` (optional): Sprint settings object

`zenhub_add_issues_to_sprints`

Add issues to sprints.

• `issue_ids` (required): Array of issue IDs
• `sprint_ids` (required): Array of sprint IDs

Architecture

The server uses a modular architecture for easy expansion:

src/
├── index.ts           # Main MCP server
├── types.ts           # TypeScript interfaces
└── tools/
    ├── index.ts       # Tool registry
    ├── base.ts        # Base tool class
    ├── queries.ts     # Query tools
    ├── issues.ts      # Issue management tools
    ├── epics.ts       # Epic management tools
    ├── workspaces.ts  # Workspace management tools
    └── sprints.ts     # Sprint management tools

Adding New Tools

1. Create a new tool class extending `BaseTool` in the appropriate category file

2. Add it to the tool export array

3. The tool will automatically be registered with the MCP server

Available Operations Reference

All 176 available ZenHub GraphQL operations are documented in:

• `zenhub_api_operations.json` - Complete operation list with descriptions
• `mutations.json` - All 157 mutations
• `queries.json` - All 19 queries

Current implementation covers 54 of 176 operations (30.7%)

Development

npm run dev

Environment Variables

• `ZENHUB_API_KEY` (required): Your ZenHub API key from ZenHub Settings
• `ZENHUB_MCP_CUSTOM_INSTRUCTIONS` (optional): Provide additional instructions for the MCP server. If set, this value will be appended to the default instructions that the server sends to the model. Use regular newlines or `\n` escape sequences to format multi-line prompts.

GraphQL Endpoint

This server connects to: `https://api.zenhub.com/public/graphql`