ZenHub

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

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

Get your ZenHub API key fromZenHub Settings

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

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

- 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_" } }

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

The server provides54 toolsacross 10 categories, implementing the most commonly used ZenHub operations:

No API key required in tool calls- SetZENHUB_API_KEYenvironment variable once and use all tools!

Execute any GraphQL query against the ZenHub API.

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

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

Search and filter issues inside repository.

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

Get all issues in a workspace (paginated).

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

Lookup an issue by repository and issue number.

- repository_gh_id(required): GitHub repository ID
- issue_number(required): Issue number

Lookup repositories by their GitHub IDs.

- repository_gh_ids(required): Array of GitHub repository IDs

- 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

- issue_ids(required): Array of issue IDs

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

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)

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

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

- issue_id(required): Issue ID
- value(required): Estimate value

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

- issue_ids(required): Array of issue IDs
- epic_ids(required): Array of epic IDs

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

Get all workspaces accessible to the current user.

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

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)

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)

- 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

- 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

- issue_ids(required): Array of issue IDs
- sprint_ids(required): Array of sprint IDs

The server uses amodular architecturefor 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

- Create a new tool class extendingBaseToolin the appropriate category file
- Add it to the tool export array
- The tool will automatically be registered with the MCP server

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 covers54 of 176 operations (30.7%)

- ZENHUB_API_KEY(required): Your ZenHub API key fromZenHub 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\nescape sequences to format multi-line prompts.

Interact with the ClickUp API to manage tasks, lists, and spaces, automating project planning and workflows.