Tokenless Zendesk

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

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)

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.