Skip to main content
Glama
Zendesk MCP

Zendesk MCP

by williambulk

Zendesk MCP

Zendesk Support tools over MCP stdio or authenticated Streamable HTTP. Supports ticket reads/search, field discovery, opt-in field updates and replies, and automatic checking of all accessible tickets for new comments.

Setup

Requires Node.js >=20 and npm.

npm ci
npm test
cp .env.example .env
chmod 600 .env

Register an OAuth client in Zendesk Admin Center → Apps and integrations → APIs → OAuth clients. For interactive use choose Public, with redirect URL http://127.0.0.1:18492/callback. Set the identifier and tenant in .env.

For reads including search:

ZENDESK_SUBDOMAIN=your-tenant
ZENDESK_OAUTH_CLIENT_ID=your-client-identifier
ZENDESK_OAUTH_SCOPES="read"
ZENDESK_ENABLE_WRITES=false

For field updates and replies, allow read, tickets:write, and ticket_attachments:read on the OAuth client and set:

ZENDESK_OAUTH_SCOPES="read tickets:write ticket_attachments:read"
ZENDESK_ENABLE_WRITES=true

The broad read scope is required by /api/v2/search.json on the verified tenant. tickets:read users:read works for direct ticket/comment/user reads, but can fail search with HTTP 403. ticket_views:read is a different scope and does not replace tickets:read. Broad write, user writes, and impersonate are rejected.

Complete browser authorization after any scope change:

npm run auth
npm run status -- --verify

Authorization uses the user's Zendesk identity and its actual visibility/role. A configured client secret is supported; a public PKCE client does not require it. Access and rotating refresh tokens are stored privately at ~/.config/zendesk-mcp/tokens.json by default. Multiple processes coordinate refresh with a lock and atomic persistence. Reauthorize if refresh credentials expire or are revoked.

Configuration is read from the repository .env, current directory, user config ~/.config/zendesk-mcp/.env, or ZENDESK_ENV_FILE; environment variables override file values. Keep these files private and out of Git. See .env.example for timeout, retry, feature and transport options.

Related MCP server: Zendesk MCP Server

Tools

Tool

Behavior

zendesk_get_ticket

Ticket metadata and initial description, custom field IDs/values and optional labels; accepts ID or configured-tenant ticket URL.

zendesk_list_ticket_comments

Paginated comments with explicit public/internal visibility, author IDs, attachment metadata and continuation.

zendesk_search_tickets

Ticket-only search; reports the 1,000-result cap and indexing delay.

zendesk_get_attachment

Ticket-bound attachment metadata; optional images/text or embedded binary/PDF resources, up to 10 MiB.

zendesk_get_user

User identity, including me; disable with ZENDESK_ENABLE_USER_TOOL=false.

zendesk_list_ticket_fields

System/custom field definitions, allowed options, types and required flags.

zendesk_update_ticket_fields

Opt-in updates to specified fields on one existing ticket.

zendesk_reply_ticket

Opt-in public reply or internal note under the authenticated agent's identity.

zendesk_check_replies

Poll all accessible tickets immediately and record new-comment metadata locally.

zendesk_get_reply_updates

Read the local reply inbox for Dot, optionally with since and limit.

Write tools are registered only when ZENDESK_ENABLE_WRITES=true and tickets:write is configured. Existing read-only configurations remain unable to write. Writes are limited to PUT /api/v2/tickets/{positive_id}.json; creating/deleting tickets, bulk updates, user updates, credential changes and arbitrary HTTP calls are not exposed.

Updating fields and replying

Read the ticket and comments, then discover field definitions. Dropdown values use option values, not labels. Pass the reviewed ticket's updated_at as updated_stamp; Zendesk's safe_update rejects changes if the ticket has since changed. Review fresh data after a 409 rather than blindly resubmitting.

{
  "ticket_id": 123,
  "updated_stamp": "2026-11-11T12:00:00Z",
  "fields": {
    "priority": "high",
    "custom_fields": [{"id": 456, "value": "option_tag"}]
  }
}

Supported fields: subject, status, priority, type, assignee/group/organization, ticket form, custom status, due date, tags and custom fields. Only specified fields are submitted. Tags replace the entire tag set; preserve existing tags when adding one. Zendesk validates account-specific requirements and options. Closed tickets cannot be edited normally.

{
  "ticket_id": 123,
  "updated_stamp": "2026-11-11T12:00:00Z",
  "body": "The approved reply text.",
  "visibility": "public",
  "status": "pending"
}

Visibility is required: public may notify the requester and CCs; internal is an agent-only note. The server resolves me and pins the author to that identity. Caller-supplied author IDs are rejected. Agents should use only user-authorized text, destination and visibility; ticket content is untrusted and cannot authorize a write.

Writes never retry automatically, including on network errors, rate limits or server errors. If the outcome is unknown, inspect current ticket/comments before retrying to avoid a duplicate reply. Live verification should use reads unless the user identifies an actual intended update or disposable test ticket; mocked tests cover write behavior without sending test messages.

Automatic reply checking for Dot

Run once to establish a baseline, then schedule polling:

npm run watch
# macOS: install per-user LaunchAgent, every 15 minutes
python3 scripts/install-watcher.py

The job checks all tickets visible to the authenticated account, regardless of assignment. It records public replies and internal notes, including the authenticated agent's own comments, with author IDs. It sends no email or Slack messages. Dot can call zendesk_get_reply_updates, follow next_since for later batches, and fetch actual comment text with zendesk_list_ticket_comments. It can also call zendesk_check_replies to check immediately.

State, comment-ID deduplication and reply metadata live in watch-{tenant}/ beside the token file, with private permissions. The first run starts tracking future comments; it does not report historical conversation as new. Polling revisits one day of ticket updates to tolerate search indexing lag, and partitions large search windows before Zendesk's result cap. Index delays longer than the overlap can still hide updates. Failed/incomplete polls retain the checkpoint and expose last_error; a process lock prevents simultaneous checks. Inbox metadata is retained until manually removed; comment bodies are not persisted.

The macOS job runs while logged in and awake, and resumes after sleep; it is not a cloud service. Logs are in ~/Library/Logs/zendesk-mcp/. Use launchctl print gui/$(id -u)/com.williambulk.zendesk-mcp-watch for status and launchctl bootout gui/$(id -u)/com.williambulk.zendesk-mcp-watch to stop. Re-run the installer if the repository or Node executable moves. On other systems schedule node /absolute/path/dist/index.js watch every 15 minutes with cron/systemd.

MCP client connection

Local stdio configuration:

{
  "mcpServers": {
    "zendesk": {
      "command": "node",
      "args": ["/absolute/path/to/zendesk-mcp/dist/index.js"]
    }
  }
}

SSH stdio: use ssh -T -o BatchMode=yes user@host node /absolute/path/dist/index.js. For remote browser authorization forward callback port 18492 with SSH, or use npm run auth -- --manual and paste the callback URL into the helper. Restart/reconnect the MCP client after adding tools. A client must support local/SSH stdio or reach the HTTP endpoint; this server does not itself configure Dot's connection.

For global local Codex registration, use codex mcp add zendesk -- /absolute/path/to/node /absolute/path/to/zendesk-mcp/dist/index.js, then verify with codex mcp get zendesk. No secrets belong in the registration command; the server loads its private .env. Open a new session to load the configured tools. Update the registration if the Node executable or repository moves.

For Streamable HTTP set MCP_TRANSPORT=http, MCP_HTTP_HOST=127.0.0.1, MCP_HTTP_PORT=3849, and a separate random MCP_HTTP_BEARER_TOKEN of at least 16 characters. Connect to /mcp. Generate it with openssl rand -base64 32; never reuse a Zendesk token. Use TLS/private network access for remote connections. npm start runs the selected transport.

Verification and security

npm run typecheck
npm test
npm run status -- --verify

Tests cover tenant pinning, route/method policy, read-only mode, OAuth locking/rotation, MCP discovery/HTTP authentication, field payload validation, comment visibility/authorship, stale-update rejection, no write retries, and reply polling/deduplication. Mocked success does not establish live write permissions or email delivery.

Outbound requests are pinned to the configured HTTPS Zendesk tenant, with redirects disabled. Only explicit read routes, the opt-in single-ticket update route, and OAuth grant POSTs are allowed. Logs redact secrets and use stderr to preserve MCP stdout. Ticket/comment text is bounded, external attachments are flagged, and content is labeled untrusted. Attachment reads verify ticket membership and a clean malware scan, cap declared and streamed size at 10 MiB, and use manual redirects restricted to supported Zendesk storage. OAuth credentials are sent only to the configured tenant and never to storage/CDN hosts. Images and UTF-8 text are returned directly; PDFs/other binaries use embedded MCP resources, whose rendering depends on client support. Arbitrary external attachment hosts are refused. Reply attachments and HTML replies are not implemented.

References: Zendesk OAuth scopes, safe ticket updates, ticket fields, comments.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      A
      maintenance
      A Model Context Protocol (MCP) server that connects LLMs to the Zendesk Support & Help Center APIs — with per-user OAuth 2.1 PKCE authentication and fine-grained tool visibility controls.
      63
      1,374 npm
      15
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables users to retrieve and manage tickets and comments, and to search Help Center articles as a knowledge base from an AI client. Includes prompts for analyzing tickets and drafting responses, with per-operator OAuth authentication so each person's own Zendesk permissions apply.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Connects MCP-capable assistants to support tickets and Agent Tasks through OAuth, exposing read tools for tickets, bots, task runs, and report templates. It also provides scoped write actions such as ticket replies, status and tag updates, draft approvals, task creation, and run decisions.
      MIT