Zendesk MCP server

zendesk-mcp

A Model Context Protocol server that exposes Zendesk ticket read and write tools to Claude Code and other MCP clients.

What it does

• Search, list (paginated), and fetch Zendesk tickets, comments, and attachments
• Create new tickets and update existing ticket fields (including group, custom status, and tags)
• Post public replies and internal notes
• Set ticket status and assign tickets to agents
• Browse and apply views and macros
• Look up users, groups, organizations, and custom statuses
• Read and write time-tracking entries
• Format a ticket as a Markdown issue draft for handoff to a tracker (GitLab, GitHub, Jira)
• Two MCP prompts (analyze-ticket, draft-ticket-response) for ticket analysis and response drafting
• (Optional) Expose Zendesk Help Center articles as an MCP resource
• (Optional) Read linked GitLab issues / MRs / commits via the Git-Zen Zendesk app

Prerequisites

https://.zendesk.com/admin/apps-integrations/apis/zendesk-api/oauth_clients Set the redirect URL to http://localhost:8787/callback and request scopes read write.

• Python 3.10 or newer
• A Zendesk OAuth client. A Zendesk admin can create one at:

Install

Install into a project-local virtualenv. Using a venv keeps zendesk-mcp and its dependencies isolated from your system Python and from other projects, and is the recommended path for everything below.

From a clone of this repository:

python3 -m venv .venv
.venv/bin/pip install --upgrade pip
.venv/bin/pip install -e .

For development (also installs pytest):

.venv/bin/pip install -e ".[dev]"

Throughout this README, commands use the venv's binaries via .venv/bin/.... You can instead source .venv/bin/activate once per shell and drop the prefix — the result is the same.

OAuth setup

Run the interactive setup using the venv's Python:

.venv/bin/python -m zendesk_mcp setup

You will be prompted for:

1. Your Zendesk subdomain (e.g. acme for acme.zendesk.com)
2. The OAuth client ID created by your admin
3. The OAuth client secret
4. (Optional) A Git-Zen integration field ID — see Optional: Git-Zen integration
5. (Optional) Whether to enable the Help Center knowledge base resource — see Optional: Help Center knowledge base

The setup opens a browser for the OAuth authorization step, then writes a token to ~/.config/zendesk-mcp/config.json (mode 0600).

If you have no browser, the URL is printed to the terminal — open it on any device, click Allow, and paste the resulting redirect URL back into the prompt.

Token expiry and refresh

Zendesk access tokens expire. OAuth clients created on or after 2026-04-30 get a 30-minute default lifetime; older clients issue non-expiring tokens unless an expiry is requested. Setup requests a 24-hour access token and a 90-day refresh token so the behaviour is the same either way, and the server renews the access token automatically — before it expires, and again if Zendesk rejects a token mid-request.

To make that possible, the config file also stores refreshtoken, expiresat, clientid, and clientsecret alongside the access token. Keep the file at mode 0600; it is the same trust level as the access token itself. If your OAuth client returns no refresh token, setup says so and the token is used as-is.

Re-run .venv/bin/python -m zendesk_mcp setup when:

• the refresh token expires (90 days with no use), or
• you revoke the OAuth grant in Zendesk.

In either case the tools return Zendesk authorization failed: ... Re-run: zendesk-mcp setup rather than failing opaquely.

Register with Claude Code

Shortened. The full README is on GitHub.