Tokenless Zendesk MCP Server

An MCP server for Zendesk. You sign in once in a real browser (Playwright) — any method works, including SSO and 2FA — and the resulting session cookies are then used to call the Zendesk REST API directly. No API token, OAuth client, or admin setup required: it acts with exactly your agent account's permissions.

This is the same way Zendesk's own agent web UI talks to its API — a valid session cookie is all a GET request needs (no CSRF token is required for reads).

What it can do

Reads

Tool	Description
zendesk_login	Open a visible browser to sign in (password / SSO / 2FA). Saves the session cookies + CSRF token.
zendesk_session_status	Check whether a saved session exists and is still valid (calls the API as the current user).
zendesk_list_views	List the agent's active views with numeric IDs, titles, and cached ticket counts.
zendesk_fetch_view_tickets	Fetch tickets in a view, following pagination (limit caps the count).
zendesk_search	Search via /api/v2/search — any Zendesk query string; returns results tagged by type.
zendesk_get_ticket	Subject, status, parties, tags, custom fields (incl. product), full comment thread, and attachments.
zendesk_download_attachment	Download an attachment (by its content_url from get_ticket) to a path or directory.
zendesk_requester_tickets	List the tickets a user has requested (their history) — "have they reported this before?".
zendesk_organization_tickets	List tickets belonging to an organization.
zendesk_ticket_fields	Field definitions with valid dropdown/tagger option values — look up the value to set a custom field.
zendesk_ticket_metrics	SLA / timing metrics for a ticket (reply time, resolution time, reopens, replies).
zendesk_list_macros	List active macros with ids and titles (for zendesk_apply_macro).
zendesk_search_users	Find users by free-text (name, email, …).
zendesk_get_user	Fetch one user by id.
zendesk_ticket_audits	Full audit trail (every change/event) for a ticket.
zendesk_request	Read-only passthrough to any /api/v2 endpoint — for anything the dedicated tools don't cover.

Writes (require the CSRF token — see Writes below)

Tool	Description
zendesk_add_comment	Add a public reply or internal note to a ticket.
zendesk_update_ticket	Set status, priority, type, assignee, group, tags, and custom fields (optionally with a comment).
zendesk_apply_macro	Apply a macro and persist its changes (status/fields/comment) to a ticket.

Attachments. zendesk_get_ticket returns an attachments array; each item has an id, file_name, content_url, content_type, and size. Pass an attachment's content_url to zendesk_download_attachment along with a destination (a file path, or a directory to save under the original filename). Downloads use the authenticated session, so private attachments work.

zendesk_request unlocks the rest of the Zendesk REST API for reads — e.g. tickets/123/audits, ticket_metrics, organizations, users/123, satisfaction_ratings. It is GET-only by design (write operations would require a CSRF token, which is out of scope).

How auth works

You sign in once in a real browser window. Playwright saves the resulting cookies to ~/.zendesk-mcp/storageState.json. Every other tool reads the cookies scoped to your instance and replays them as a Cookie header against https://{subdomain}.zendesk.com/api/v2/…. When the session expires the API returns 401/403 and the tool returns a clear "run zendesk_login" message.

The session file holds live auth cookies — it's git-ignored. Treat it like a password.

Writes (CSRF)

GET requests authenticate with the session cookie alone. Write requests (POST/PUT/DELETE) additionally require Zendesk's CSRF token — the same one the agent UI uses. It's captured at login (from the agent page's <meta name="csrf-token">) and saved to ~/.zendesk-mcp/csrf.txt. The token is stable for the life of the session; if it ever goes stale, the server fetches a fresh one automatically and retries the write once. The write tools (zendesk_add_comment, zendesk_update_ticket, zendesk_apply_macro) modify real tickets — confirm changes with the user before sending.

Add to Claude Code

No clone, no build — just point your MCP config at npx. Add to your .mcp.json (or Claude Desktop config), replacing youracme with your Zendesk subdomain:

{
  "mcpServers": {
    "zendesk": {
      "command": "npx",
      "args": ["-y", "tokenless-zendesk-mcp"],
      "env": {
        "ZENDESK_SUBDOMAIN": "youracme"
      }
    }
  }
}

Or with the CLI: claude mcp add zendesk -e ZENDESK_SUBDOMAIN=youracme -- npx -y tokenless-zendesk-mcp

First login

You sign in once in a real browser window. Run the bundled login subcommand (it downloads Chromium on first use, then opens the window):

ZENDESK_SUBDOMAIN=youracme npx -y tokenless-zendesk-mcp login

• macOS / Windows / Linux desktop: a Chromium window opens — sign in, done.
• WSL2: you need WSLg (Windows 11) or an X server so the window can show. If the window can't open, run the login on the Windows host, or set DISPLAY.

You can also trigger login from inside Claude with the zendesk_login tool, but the standalone command is more reliable since not every MCP host surfaces the window.

From source (contributors)

npm install
npm run build
ZENDESK_SUBDOMAIN=youracme npm run login   # one-time browser sign-in

Then point your MCP config at the build instead of npx:

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

See CONTRIBUTING.md for the release process and how publishing is configured.

Configuration (env vars)

Var	Default	Purpose
ZENDESK_SUBDOMAIN	— (required)	The {subdomain} in https://{subdomain}.zendesk.com.
ZENDESK_SESSION_DIR	~/.zendesk-mcp	Where the saved session lives.
ZENDESK_API_TIMEOUT	30000	Per-request timeout in ms.
ZENDESK_LOGIN_TIMEOUT	300000	How long the login window waits for you to finish signing in, in ms.

Verify

After building and logging in:

ZENDESK_SUBDOMAIN=youracme node scripts/verify.mjs

It calls me, listViews, search, and getTicket against your live instance.

Notes & limitations

• Auth is session-cookie based. Cookies expire (and SSO sessions time out), so you'll re-run zendesk_login periodically.
• It respects whatever permissions your agent account has — nothing more.
• The API is paginated; list tools cap results (limit) and page 100 at a time. Rate-limited (429) responses are retried honoring Retry-After.
• Writes are supported via the session CSRF token (see Writes). They act with your agent permissions — review changes before sending.