zendesk-mcp-server

# Zendesk MCP Server

[![Glama score](https://glama.ai/mcp/servers/fruggr/zendesk-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/fruggr/zendesk-mcp-server)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.fruggr%2Fzendesk--mcp--server-0a7ea4)](https://registry.modelcontextprotocol.io/?search=io.github.fruggr/zendesk-mcp-server)
[![npm version](https://img.shields.io/npm/v/@fruggr/zendesk-mcp-server?logo=npm&color=cb3837)](https://www.npmjs.com/package/@fruggr/zendesk-mcp-server)
[![License: MIT](https://img.shields.io/npm/l/@fruggr/zendesk-mcp-server?color=blue)](LICENSE)
[![Node.js](https://img.shields.io/node/v/@fruggr/zendesk-mcp-server?logo=nodedotjs&logoColor=white&color=339933)](https://nodejs.org)
[![Renovate enabled](https://img.shields.io/badge/renovate-enabled-brightgreen?logo=renovatebot&logoColor=white)](https://renovatebot.com)
[![semantic-release](https://img.shields.io/badge/semantic--release-e10079?logo=semantic-release&logoColor=white)](https://github.com/semantic-release/semantic-release)

**Bring Zendesk deep into your AI assistant.** A
[Model Context Protocol](https://modelcontextprotocol.io) (MCP) server: find
answers in the Help Center, **draft, update and translate** articles (keeping
languages in sync), and **manage Support tickets** end to end — comments, triage
and image attachments — all in plain language,
**without switching apps**.

Think of it as the [Zendesk agent for Microsoft 365 Copilot](https://support.zendesk.com/hc/en-us/articles/9958331458458-Using-the-Zendesk-agent-in-Microsoft-365-Copilot),
but **vendor-neutral** — it drops into any MCP client (Claude Desktop, Claude
Code, Cursor, VS Code, …) instead of being tied to one assistant — and it always
acts with **each user's own Zendesk permissions**, never a shared admin key.

## What your assistant can do

Ask in natural language; the assistant figures out context and intent, then calls
the right tools on your behalf:

- **Find answers in the Help Center** — "how do I request a software license?" or
  "what's the time-off policy?" surfaces the right article, by meaning, not just
  keywords.
- **Create, view and update tickets without leaving the conversation** — open a
  ticket, check its status, add a public reply or an internal note, change the
  priority or assignee, or mark it solved.
- **Summarize a ticket for reporting or a quick decision** — pull the details and
  the full comment thread and get the gist in a sentence.
- **Read the screenshots and photos attached to a ticket** — error dialogs, UI
  captures or product photos are handed to your assistant's own model as images,
  so it can describe them or act on what they show.
- **Search and triage your queue in plain language** — "show me my open tickets
  about billing from this week."
- **Draft and maintain knowledge-base articles** — write a new article, or revise
  a large one **one section at a time** so the whole HTML body never has to
  round-trip through the model.

Because it runs on the **user's own OAuth session**, the assistant only ever sees
and touches what that person is allowed to — the same scoping you'd get signing
into Zendesk directly.

## How it's different

Most Zendesk integrations use a shared admin API key, giving every user full
access to every ticket, and bolt on a fixed set of tools. This server is built
differently:

- **Per-user authentication, OAuth-only** — In both transports, auth is OAuth 2.1 PKCE: each user authenticates with their own Zendesk credentials, so the assistant sees exactly what the user is allowed to see. Static API tokens are deliberately **not** supported (see [below](#what-this-server-does-not-do)).
- **Two deployment shapes, same auth story** — Run it on your laptop as a stdio MCP server (Claude Desktop / Claude Code / VS Code) or deploy it as a private remote MCP server with one user, one Zendesk session per HTTP request.
- **Context-friendly tool modes** — Expose every operation as its own tool, group them into namespace proxies, or collapse to a single unified tool. Tools are segmented into namespaces you can selectively enable, so each context loads only the surface it needs.
- **Section-based article editing** — For large Help Center articles, read and rewrite one section at a time (parsed by h1/h2/h3 headings) instead of shuffling the full HTML body through the assistant. Reduces tokens by 10–100× on targeted edits.
- **Native multimodal attachments** — ticket images are delivered as native MCP image content for the **client's own model** to analyze: no server-side vision model, **no extra API key**, fully vendor-neutral (see [Attachments & vision](#attachments--vision)).
- **Read-only mode** — Restrict the server to read operations only, ideal for assistants that should never modify data.
- **Lean stack** — Built on the official `@modelcontextprotocol/sdk` plus `zod`.

Under the hood it speaks to the **Zendesk Support & Help Center (Guide) APIs**,
runs locally over **stdio** or as a private **remote MCP server** over HTTP, and
ships fine-grained tool-visibility controls — the specifics are below.

### Attachments & vision

Ticket image attachments are returned as **native MCP multimodal content**, so the
assistant's own model (Claude, GPT, Gemini, …) sees the pixels directly. There is
no server-side vision model and **no extra API key** — the opposite of servers
that expose an `analyze_ticket_images`-style tool calling a vision model with the
operator's own key.

| | This server | Server-side-analysis alternatives |
|---|---|---|
| Who sees the image | The **client's own model** receives the pixels as multimodal input | The **server** calls a vision model with **its own API key** |
| Extra dependencies | None | Vision-model API key + billing on the server |
| Vendor neutrality | ✅ Full | ❌ Locked to one provider |

Non-image attachments come back as text references. The per-image size cap and the
number of embedded images are **configurable** — see
[`ZENDESK_MAX_ATTACHMENT_BYTES`](docs/configuration.md#zendesk_max_attachment_bytes)
and [`ZENDESK_MAX_EMBEDDED_IMAGES`](docs/configuration.md#zendesk_max_embedded_images).

## When to use this server

**Reach for it when:**

- You want an LLM to read or triage **Zendesk tickets** and **Help Center articles** on behalf of a real user, with that user's own permissions — not a shared admin key.
- You're editing **large Help Center articles** and want section-scoped reads/rewrites instead of round-tripping the full HTML body through the model.
- You need to **cap the tool surface** — read-only assistants, a single namespace, or one unified tool to fit a tight context budget.
- You run a **stdio MCP client** (Claude Desktop, Claude Code, Cursor, VS Code, Cline, …) and want a `npx`-installable server with no extra infrastructure, **or** you want to **deploy it as a private remote MCP server** that web/native clients reach over HTTP — each MCP client still carries its own user's OAuth token.

**Look elsewhere when:**

- You need Zendesk products outside Support & Guide (e.g. Talk, Explore analytics, Sell) — those endpoints aren't covered.
- You need a single shared service account, or static API-token auth — this server doesn't support either, by design (see [What this server does *not* do](#what-this-server-does-not-do)).

## What this server does *not* do

**No API-token authentication.** This server is OAuth 2.1 PKCE only — there is no `ZENDESK_EMAIL` + `ZENDESK_API_TOKEN` (Basic auth) mode, in any transport. This is a deliberate design choice:

- **API tokens are insufficiently secure.** A Zendesk API token is a long-lived, static, shared secret that carries the full rights of the issuing user — no per-user scoping, no short expiry, no per-user consent or revocation. OAuth 2.1 PKCE issues per-user, revocable tokens instead, so the LLM only ever sees what the authenticated user is allowed to see.
- **API tokens don't scale.** A single static credential can't attribute actions to individual users or be revoked granularly, and it makes a multi-user remote deployment unsafe (in HTTP it would expose the issuing user's rights to every caller). OAuth scales naturally: each MCP client carries its own user's token.

If you specifically need an API-token / service-account mode (e.g. headless CI with a shared account), use one of the other Zendesk MCP servers that support it — see [Inspiration & related projects](#inspiration--related-projects).

## Use cases

| Persona | Transport | Auth | Quick start |
|---------|-----------|------|-------------|
| **Run it on your laptop** — single user, plugged into Claude Desktop / Claude Code / VS Code | `stdio` (default) | OAuth 2.1 PKCE in your browser | [Quick start: local](#quick-start-local-stdio) |
| **Deploy a private remote MCP server** — one server per Zendesk account, each MCP client carries its own user's OAuth token | `http` | Per-user OAuth 2.1 PKCE bearer in `Authorization:` header | [Quick start: remote](#quick-start-remote-http) |

## Tool modes

The server registers tools in one of three modes, controlled by `--mode`:

| Mode | Tools exposed | Best for |
|------|--------------|----------|
| **`all`** | Every operation as its own tool (`get_ticket`, `search_articles`, ...) | Clients with good tool selection, full granularity |
| **`namespace`** (default) | One proxy tool per namespace (`zendesk_tickets`, `zendesk_help_center`, `zendesk_users`) | Balanced context usage, grouped operations |
| **`single`** | A single proxy tool (`zendesk`) | Minimal context footprint, single entry point |

In `namespace` and `single` modes, the proxy tool accepts `{ "operation": "<tool_name>", "params": { ... } }` and dispatches to the appropriate handler after validating params through the original Zod schema. Proxy descriptions include only the first sentence of each sub-operation to stay compact; the full schema is applied when the operation is actually called.

> **Tip:** The `single` mode is particularl