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

Writes (require the CSRF token — see Writes below)

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).

Related MCP server: reddit-mcp

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.

Setup

npm install        # also runs `playwright install chromium`
npm run build

First login

The login step needs a visible browser, so it needs a display.

ZENDESK_SUBDOMAIN=youracme npm run 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 npm run login can't open a window, run the login step on the Windows host, or set DISPLAY to your X server.

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

Add to Claude Code

claude mcp add zendesk -- node /path/to/tokenless-zendesk-mcp/dist/index.js

Or add to your MCP config (.mcp.json / Claude Desktop config):

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

Configuration (env vars)

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.