@mindstone/mcp-server-zendesk

Zendesk Support MCP server — tickets, users, comments, macros, account setup, and support-workflow discovery through a standard stdio MCP package.
Best for support teams that want an assistant to triage, summarize, and update Zendesk tickets from a local MCP host.
Status
Why this exists
Zendesk has announced its own MCP client and server experiences for broader platform integration. This package is for MCP hosts that want a local Zendesk Support connector they can install and run directly.
It helps an assistant do the support work humans usually ask for: find urgent tickets, pull the latest context, draft or add comments, apply macros, look up users and organizations, and inspect support setup. The benefit is faster ticket triage and follow-up while treating customer-authored ticket text as something to quote and summarize, not as instructions to obey.
Example interaction
"Find high-priority open Zendesk tickets and show me the latest details for the first one."
Tools the host calls:
search_zendesk_tickets — searches type:ticket status:open priority:high and returns ticket summaries.
get_zendesk_ticket — fetches the selected ticket, including wrapped subject and description text.
Response (trimmed):
{
"ok": true,
"ticket": {
"id": 12345,
"status": "open",
"priority": "high",
"subject": "<untrusted-content source=\"external-ticket\">Login issue</untrusted-content>",
"description": "<untrusted-content source=\"external-ticket\">Customer cannot access the admin dashboard.</untrusted-content>"
}
}
Requirements
One-click install

After clicking the button, your host will prompt you to fill: ZENDESK_CONFIG_PATH, ZENDESK_CLIENT_SECRET.
Manual config for Claude Desktop / Claude Code / Goose / Continue.dev (Zendesk)
{
"mcpServers": {
"Zendesk": {
"command": "npx",
"args": [
"-y",
"@mindstone/mcp-server-zendesk"
],
"env": {
"ZENDESK_CONFIG_PATH": "~/.mcp/zendesk",
"ZENDESK_CLIENT_SECRET": ""
}
}
}
}
Quick Start
Install & build
cd <path-to-repo>/connectors/zendesk
npm install
npm run build
npx (once published)
npx -y @mindstone/mcp-server-zendesk
Local
Configuration
Environment variables
ZENDESK_CONFIG_PATH — path to the config directory that contains accounts.json and credentials/
ZENDESK_CLIENT_ID — OAuth client ID used to renew sign-ins whose token file doesn't carry its own client_id; read when a refresh happens
ZENDESK_CLIENT_SECRET — only for confidential OAuth clients, and only sent together with ZENDESK_CLIENT_ID; public (PKCE) clients need none
MCP_HOST_BRIDGE_STATE — optional path to a host bridge state file used for credential management
MINDSTONE_REBEL_BRIDGE_STATE — backwards-compatible alias for MCP_HOST_BRIDGE_STATE
Authentication
Each account uses one of two kinds of credential. For a given subdomain, an OAuth sign-in wins over an API token.
OAuth sign-in (preferred). The host app runs the Zendesk sign-in (for example, an authorization-code flow with PKCE) and writes the result to credentials/<subdomain>.token.json under ZENDESK_CONFIG_PATH, owner-only (0600):
{
"access_token": "…",
"refresh_token": "…",
"expires_in": 1800,
"expires_at": 1767225600000,
"token_type": "bearer",
"subdomain": "acme",
"email": "agent@example.com",
"client_id": "your-oauth-client-id",
"scope": "read write"
}
expires_at is a millisecond timestamp. client_id and scope are optional; when present, refreshes use that client and ask for the same scope.
The connector renews the access token itself, within five minutes of expiry or after a 401:
- It sends a JSON request to
https://<subdomain>.zendesk.com/oauth/tokens with the refresh token and the client id (the token file's client_id, else ZENDESK_CLIENT_ID). No client secret is needed for a public client.
- Concurrent tool calls share one refresh, and the token file is re-read first, so a token renewed by another process is used rather than spent again.
- The rotated refresh token is saved by replacing the file atomically, and only if the file still holds the refresh token that was just spent. A token file that was removed while a refresh was running (the account was disconnected) is not recreated, and one replaced by a new sign-in is kept and used instead.
- If the renewed token can't be saved (a full or read-only disk), the connector keeps using it in memory and doesn't send the spent refresh token again;
list_zendesk_accounts shows a warning on that account until the file changes. After a restart, the account may need to sign in again.
- If Zendesk refuses the refresh token (
invalid_grant, invalid_client, unauthorized_client), or there is no client id, tool calls fail with AUTH_FAILED and "Reconnect Zendesk…", and list_zendesk_accounts reports reconnect-required. The token file is kept; signing in again replaces it.
- A temporary failure (server error, rate limit, network) returns
AUTH_REFRESH_FAILED ("try again in a moment") once the access token has expired; the next call tries again.
API token. An entry with subdomain, email and apiToken in accounts.json (see below), sent as HTTP Basic auth. API tokens don't expire, so they are always active.
Standalone config directory
To use an API token, create a config directory and accounts.json file:
mkdir -p ~/.mcp/zendesk
cat > ~/.mcp/zendesk/accounts.json <<'EOF'
{
"accounts": [
{
"subdomain": "yourcompany",
"email": "you@example.com",
"apiToken": "your-zendesk-api-token"
}
],
"defaultSubdomain": "yourcompany"
}
EOF
Host configuration examples
Claude Desktop / Cursor
{
"mcpServers": {
"Zendesk": {
"command": "npx",
"args": ["-y", "@mindstone/mcp-server-zendesk"],
"env": {
"ZENDESK_CONFIG_PATH": "~/.mcp/zendesk"
}
}
}
}
Local development (no npm publish needed)
{
"mcpServers": {
"Zendesk": {
"command": "node",
"args": ["<path-to-repo>/connectors/zendesk/dist/index.js"],
"env": {
"ZENDESK_CONFIG_PATH": "~/.mcp/zendesk"
}
}
}
}
Mindstone Rebel
"Zendesk": {
"name": "Zendesk",
"type": "stdio",
"command": "node",
"args": ["<path-to-repo>/connectors/zendesk/dist/index.js"],
"env": {
"ZENDESK_CONFIG_PATH": "~/Library/Application Support/mindstone-rebel/mcp/zendesk",
"MCP_HOST_BRIDGE_STATE": "~/Library/Application Support/mindstone-rebel/mcp/rebel-inbox-bridge.json"
},
"description": "Zendesk support tickets...",
"catalogId": "bundled-zendesk"
}
Account management
list_zendesk_accounts — List connected accounts with auth status
remove_zendesk_account — Disconnect a Zendesk account
authenticate_zendesk_account — Connect using API token
Tickets
search_zendesk_tickets — Search with Zendesk query syntax (max 1000 results)
export_zendesk_tickets — Cursor-based export with no 1000-result limit
get_zendesk_ticket — Get single ticket by ID
get_zendesk_tickets_by_ids — Batch-fetch multiple tickets
create_zendesk_ticket — Create a new ticket
update_zendesk_ticket — Update ticket fields, status, or add comment
Users
search_zendesk_users — Search by name, email, or query
get_zendesk_user — Get user by ID
create_or_update_zendesk_user — Create a user or update the one with the same email
list_zendesk_ticket_comments — List conversation thread with author resolution
add_zendesk_ticket_comment — Add public reply or internal note
Discovery
list_zendesk_groups — List agent groups
list_zendesk_ticket_fields — List ticket fields including custom fields
list_zendesk_views — List saved ticket views
list_zendesk_view_tickets — Execute a view and list its tickets
list_zendesk_organizations — List organizations
get_zendesk_organization — Get a single organization by ID
Macros
list_zendesk_macros — List or search macros
get_zendesk_macro — Get macro details
apply_zendesk_macro — Preview and apply macro to ticket
Help Center
search_zendesk_help_center_articles — Search knowledge-base articles
get_zendesk_help_center_article — Read a full Help Center article
Satisfaction
list_zendesk_satisfaction_ratings — List CSAT ratings with score/date filters
Security notes
- Zendesk API-token credentials live in
accounts.json; OAuth credentials are read from credentials/*.token.json under ZENDESK_CONFIG_PATH. Renewed tokens are written to a 0600 temp file in the same folder and renamed into place; token files are never deleted on a failed refresh.
- Access tokens, refresh tokens and the token endpoint's error descriptions are never logged; only HTTP status and OAuth error codes are.
- Host bridge calls, when configured, go to
127.0.0.1 using the token from MCP_HOST_BRIDGE_STATE.
- Ticket subjects, descriptions, comment bodies, user/org/group/macro/view/field text, and other externally authored strings are wrapped in
<untrusted-content source="...">...</untrusted-content> envelopes with close-tag escaping before model exposure.
- Ticket exports that write files are constrained to the system temp directory (symlink-safe canonical containment) and are created inside a fresh private per-export directory with owner-only permissions — only the requested file name is honoured, the full path is returned as
file_path, and pre-existing files are never touched. export_zendesk_tickets and get_zendesk_tickets_by_ids are annotated as non-read-only because they can write local export files.
- Email inputs are validated for format and phone inputs for E.164 before any network call; numeric IDs and pagination parameters must be positive integers.
- Account removal, ticket updates, ticket comments, and macro application are marked so capable hosts can ask before changing support data.
Smoke test
Ask your MCP host to run:
List my open Zendesk tickets
If that fails, confirm that:
dist/index.js exists (run npm run build)
ZENDESK_CONFIG_PATH points to a readable directory
accounts.json contains a valid subdomain, email, and API token
Troubleshooting
| Symptom | Likely cause | Fix |
|---|
| Connector fails to start | Not built yet | Run npm install && npm run build |
| Auth error or empty results | Wrong config path or invalid credentials | Check ZENDESK_CONFIG_PATH and accounts.json |
AUTH_FAILED with "Reconnect Zendesk" | The OAuth sign-in was revoked, expired from disuse, or has no client id to renew with | Sign in to Zendesk again from the host app |
AUTH_REFRESH_FAILED | Zendesk couldn't be reached to renew the sign-in | Try again in a moment |
| MCP host reports protocol issues | Stdout noise in stdio session | Ensure no console.log calls (all logging uses console.error) |
Licence
FSL-1.1-MIT — Functional Source License, Version 1.1, with MIT future licence. The software converts to MIT licence on 2030-04-08.