michaelrice/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
- Python 3.10 or newer
- A Zendesk OAuth client. A Zendesk admin can create one at:
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.
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:
For development (also installs pytest):
> 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:
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 refresh_token, expires_at,
client_id, and client_secret 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
Register the MCP server using the venv's Python by absolute path. Claude Code launches the server in a fresh shell that does **not** inherit your activated venv, so the absolute path is required — pointing at a bare python here will fail to import zendesk_mcp.
Or just inline the absolute path you want:
Then add the read tools to permissions.allow in ~/.claude/settings.json to avoid per-call prompts:
Write tools (zendesk_post_comment, zendesk_post_internal_note, zendesk_set_ticket_status, zendesk_assign_ticket, zendesk_create_ticket, zendesk_update_ticket, zendesk_log_time, zendesk_add_tag, zendesk_remove_tag, zendesk_apply_macro) are intentionally not in the default allow-list — Claude will prompt you per call.