reminia/zendesk-mcp-server

A Model Context Protocol server for Zendesk.
This server provides a comprehensive integration with Zendesk. It offers:
Tools for retrieving and managing Zendesk tickets and comments
Specialized prompts for ticket analysis and response drafting
Full access to the Zendesk Help Center articles as knowledge base
## Setup
build: uv venv && uv pip install -e . or uv build in short.
configure authentication: see Authentication below.
configure in Claude desktop:
json
"mcpServers": {
"zendesk": {
"command": "uv",
"args": [
"--directory",
"/path/to/zendesk-mcp-server",
"run",
"zendesk"
## Authentication
This server authenticates with OAuth. Each operator authorizes with their own
Zendesk login, so API calls carry their identity and Zendesk applies exactly the
permissions it applies in the UI — their role, their group restrictions, their
ticket access. Comments they post are authored by them.
API token authentication still works but is deprecated. See
Migrating from an API token.
### 1. Register a public OAuth client
In Admin Center, go to Apps and integrations > APIs > OAuth clients and
create a client:
| Field | Value |
| Client kind | Public — this server runs on each operator's machine, so there is no secret it could keep. PKCE is used instead. |
| Redirect URLs | http://localhost:4567/callback |
| Allowed scopes | tickets:read tickets:write ticketattachments:read users:read hc:read |
Setting Allowed scopes is optional but recommended: it caps what any token
from this client can ever request, even if the code changes.
Note the client's Identifier — that is the ZENDESKCLIENTID below.
If Zendesk rejects http://localhost:4567/callback, register https://localhost
instead and use zendesk-auth --manual in step 3.
### 2. Configure the environment
Copy .env.example to .env and set:
bash
ZENDESKSUBDOMAIN=acme # for https://acme.zendesk.com
ZENDESKCLIENTID=your-client-identifier
Keep .env out of version control.
Two optional settings, both of which must agree with the OAuth client:
| Variable | Default | When to change it |
| ZENDESKOAUTHREDIRECTURI | http://localhost:4567/callback | Port 4567 is in use, or the client is registered with a different redirect URL. Must match a redirect URL on the client exactly. |
| ZENDESKTOKENFILE | $XDGCONFIGHOME/zendesk-mcp/tokens.json | Storing tokens elsewhere, for example a Docker volume. |
### 3. Authorize this machine, once
bash
uv run zendesk-auth
This opens a browser, asks the operator to approve access, and stores the
resulting tokens locally. From then on the server renews access on its own; the
operator never repeats this unless the tokens are revoked or left unused past the
refresh token's lifetime (90 days as requested by this server).
If the browser cannot reach this machine — a remote shell, or an OAuth client
registered with https://localhost — use the paste-based flow instead:
bash
uv run zendesk-auth --manual
Tokens are written to $XDGCONFIGHOME/zendesk-mcp/tokens.json
(~/.config/zendesk-mcp/tokens.json by default), created 0600 inside a 0700
directory. Override the location with ZENDESKTOKENFILE. The file holds live
credentials: treat it like a password and never commit it.
### How token renewal works