{
  "markdown": "# Zendesk MCP Server\n\n[![Glama score](https://glama.ai/mcp/servers/fruggr/zendesk-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/fruggr/zendesk-mcp-server)\n[![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)\n[![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)\n[![License: MIT](https://img.shields.io/npm/l/@fruggr/zendesk-mcp-server?color=blue)](LICENSE)\n[![Node.js](https://img.shields.io/node/v/@fruggr/zendesk-mcp-server?logo=nodedotjs&logoColor=white&color=339933)](https://nodejs.org)\n\nA [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that\nputs Zendesk inside your AI assistant. It finds answers in the Help Center;\ndrafts, updates and translates articles while keeping the languages in sync; and\nhandles Support tickets end to end, comments, triage and image attachments\nincluded. It all happens in plain language, without switching apps.\n\nIt does roughly what the\n[Zendesk agent for Microsoft 365 Copilot](https://support.zendesk.com/hc/en-us/articles/9958331458458-Using-the-Zendesk-agent-in-Microsoft-365-Copilot)\ndoes, minus the tie to one vendor: it drops into any MCP client (Claude Desktop,\nClaude Code, Cursor, VS Code, and the rest). And it always acts with each user's\nown Zendesk permissions, never a shared admin key.\n\n## What your assistant can do\n\nAsk in natural language; the assistant works out the context and the intent,\nthen calls the right tools on your behalf.\n\n- Find answers in the Help Center. \"How do I request a software license?\" or\n  \"what's the time-off policy?\" surfaces the right article, matched by meaning\n  rather than by keyword.\n- Create, view and update tickets without leaving the conversation: open a\n  ticket, check its status, add a public reply or an internal note, change the\n  priority or the assignee, mark it solved.\n- Summarize a ticket for a report or a quick decision. The assistant pulls the\n  details and the full comment thread and gives you the gist in a sentence.\n- Read the screenshots and photos attached to a ticket. Error dialogs, UI\n  captures and product photos are handed to your assistant's own model as\n  images, so it can describe them or act on what they show.\n- Search and triage your queue in plain language: \"show me my open tickets about\n  billing from this week.\"\n- Draft and maintain knowledge-base articles. You can write a new one, or revise\n  a large one a single section at a time, so the whole HTML body never has to\n  round-trip through the model.\n\n## Why this server\n\nMost Zendesk integrations run on a shared admin API key, which hands every user\nfull access to every ticket, and bolt on a fixed set of tools. This one is built\ndifferently.\n\n- Per-user authentication, OAuth only. Both transports use OAuth 2.1 PKCE: each\n  user signs in with their own Zendesk credentials, so the assistant sees and\n  touches exactly what that person is allowed to, the same scoping you get by\n  signing into Zendesk directly. Static API tokens are deliberately not\n  supported ([why](#what-this-server-does-not-do)).\n- Section-based article editing. For large Help Center articles, read and\n  rewrite one section at a time (parsed by `h1`/`h2`/`h3` headings) instead of\n  shuffling the full HTML body through the assistant. On a targeted edit that\n  cuts tokens by a factor of 10 to 100.\n- Native multimodal attachments. Ticket images come back as native MCP image\n  content, so the client's own model (Claude, GPT, Gemini, whichever) sees the\n  pixels directly. No server-side vision model, no extra API key, and nothing\n  tying you to one provider. Non-image attachments come back as text references,\n  and both image caps are configurable.\n- A tool surface you can cap. Expose every operation as its own tool, group them\n  into namespace proxies, or collapse everything into a single unified tool. You\n  can also filter by namespace or down to read-only operations, so each context\n  loads only the surface it needs (see [Tool surface](#tool-surface)).\n- Two deployment shapes, same auth story. Run it on your laptop as a stdio MCP\n  server, or deploy it as a private remote MCP server reached over HTTP, with one\n  Zendesk session per request and each client carrying its own user's token.\n- A lean stack: the official `@modelcontextprotocol/sdk` plus `zod`, speaking to\n  the Zendesk Support and Help Center (Guide) APIs.\n\nLook elsewhere when:\n\n- You need Zendesk products outside Support and Guide (Talk, Explore analytics,\n  Sell). Those endpoints aren't covered.\n- You need a single shared service account, or static API-token auth. This\n  server supports neither, by design (see below).\n\n## What this server does *not* do\n\nThere is no API-token authentication. The server speaks OAuth 2.1 PKCE and\nnothing else: no `ZENDESK_EMAIL` + `ZENDESK_API_TOKEN` (Basic auth) mode, in any\ntransport. That is deliberate, for two reasons.\n\n1. **API tokens are insufficiently secure.** A Zendesk API token is a\n   long-lived, static, shared secret that carries the full rights of the user\n   who issued it. There is no per-user scoping, no short expiry, and no per-user\n   consent or revocation. OAuth 2.1 PKCE issues per-user, revocable tokens\n   instead.\n2. **API tokens don't scale.** A single static credential can't attribute\n   actions to individual users, and it can't be revoked granularly. It also\n   makes a multi-user remote deployment unsafe: over HTTP it would expose the\n   issuing user's rights to every caller.\n\nIf you specifically need an API-token or service-account mode (headless CI with\na shared account, say), use one of the other Zendesk MCP servers that support\nit. A few are listed under\n[Inspiration & related projects](#inspiration--related-projects).\n\n## Quick start: local (stdio)\n\nThe default shape: one developer, one Zendesk account, OAuth 2.1 PKCE in the\nbrowser. You need **Node.js >= 20** and a **Zendesk** instance (Support or\nSuite).\n\n### Install\n\n```bash\n# Run without installing\nnpx -y @fruggr/zendesk-mcp-server <your-subdomain>\n\n# Or install globally\nnpm install -g @fruggr/zendesk-mcp-server\nzendesk-mcp-server <your-subdomain>\n```\n\nSigning in needs a Zendesk OAuth client, so register one first (next section).\n\n### Zendesk OAuth setup\n\n1. Go to **Admin Center → Apps and integrations → APIs → OAuth Clients**\n2. Create a **public** client:\n   - **Identifier**: `<your-subdomain>_zendesk` (or set `ZENDESK_OAUTH_CLIENT_ID`)\n   - **Redirect URL**: `http://localhost:27439/callback` (change the port to match\n     `ZENDESK_OAUTH_CALLBACK_PORT` / `--callback-port` if you override it; Zendesk\n     accepts several redirect URLs, one per line)\n\nOn the first tool call the server starts the sign-in flow: it opens a browser\nwindow and returns the authorize URL in a tool message. The call does not block\nwaiting for sign-in, so authenticate in the browser and then retry the request.\nThe token is persisted to an owner-only file and reused across restarts, so you\ndon't authenticate again every time your MCP client respawns the server (path\nand overrides: [`ZENDESK_TOKEN_FILE`](docs/configuration.md#zendesk_token_file)).\n\n### MCP client wiring\n\n<details>\n<summary><strong>Claude Desktop</strong></summary>\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"zendesk\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@fruggr/zendesk-mcp-server\", \"<your-subdomain>\", \"--mode\", \"single\"]\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><strong>Claude Code</strong></summary>\n\n```bash\nclaude mcp add zendesk -- npx -y @fruggr/zendesk-mcp-server <your-subdomain> --mode single\n```\n\n</details>\n\n<details>\n<summary><strong>VS Code (Copilot / Continue / Cline)</strong></summary>\n\nAdd to your `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"zendesk\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@fruggr/zendesk-mcp-server\", \"<your-subdomain>\", \"--mode\", \"single\"]\n    }\n  }\n}\n```\n\n</details>\n\nSomething not working? See [Troubleshooting](docs/troubleshooting.md).\n\n## Quick start: remote (HTTP)\n\n> **Experimental.** The HTTP transport ships, but it has not yet been exercised\n> end-to-end against a real Zendesk tenant from every MCP client. Local stdio is\n> the supported path.\n\nYou can also deploy a private remote MCP server for **one** Zendesk account,\nwhere every MCP client presents its **own** user's OAuth bearer in\n`Authorization:` and the server never sees a shared admin key. The full guide\ncovers OAuth setup, `--public-url` behind a reverse proxy, per-platform config,\nthe discovery endpoints, MCP client wiring, CORS and what stays the operator's\njob: **[docs/http-deployment.md](docs/http-deployment.md)**.\n\n## Tool surface\n\nTools are grouped into four namespaces: **Tickets**, **Help Center**, **Users &\nOrganizations** and **Search**. The server registers them in one of three modes,\nso you can trade granularity against context budget:\n\n- **`all`**: every operation as its own tool, for clients with good tool selection;\n- **`namespace`** (default): one proxy tool per namespace, a balanced middle ground;\n- **`single`**: a single `zendesk` tool, for models with limited tool slots.\n\nProxies take `{ \"operation\": \"<tool_name>\", \"params\": { … } }` and validate\n`params` through the original schema. `--namespace`, `--tool` and `--read-only`\nfilter tools *before* the proxies are built, so each proxy describes only the\noperations that survive.\n\nEvery tool with its description and its `read`/`write` mode:\n**[docs/mcp-tools-reference.md](docs/mcp-tools-reference.md)**. The flags and\nworked examples: **[docs/configuration.md](docs/configuration.md)**.\n\n## Help Center context\n\nBeyond tools, the server hands the LLM the structure of *your* Help Center: the\nactive locales, the category → section tree with IDs, the visibility segments\nand the permission groups. With those in hand it uses real IDs instead of\nguessing or fuzzy-matching names. It all arrives through MCP-native channels,\nnamely the `instructions` blob sent on `initialize` plus pull-only resources for\nthe topology and for reading (or pinning) individual articles. The resources are\nfetched with the caller's own token, and clients that don't support resources\nignore them silently.\n\nWhat's exposed, what the promoted-article pre-listing costs in requests, and how\nto turn each piece off: **[docs/help-center-context.md](docs/help-center-context.md)**.\n\n## Configuration\n\nThe complete reference for the CLI flags (`--mode`, `--namespace`,\n`--read-only`, `--transport`, `--public-url`, and so on) and the environment\nvariables (`ZENDESK_SUBDOMAIN`, `ZENDESK_TOKEN_FILE`, `PUBLIC_URL`, the\nattachment-vision caps) lives in\n**[docs/configuration.md](docs/configuration.md)**. Every variable has its own\nanchor, so you can deep-link a specific setting.\n\n## Troubleshooting\n\nBrowser not opening during OAuth login, the callback port already in use, having\nto re-authenticate every time, and `Permission denied` on the Guide-admin\nendpoints are covered in **[docs/troubleshooting.md](docs/troubleshooting.md)**.\nRestart with `LOG_LEVEL=debug` for the full OAuth flow trace.\n\n## Development\n\nSetting up the repo, the toolchain, dev mode and how to test a PR branch are\ncovered in **[CONTRIBUTING.md](CONTRIBUTING.md#development-setup)**. Architecture\nand code-style conventions live in [`AGENTS.md`](AGENTS.md).\n\n## FAQ\n\n**Which Zendesk products are supported?**\nZendesk Support (tickets, users, organizations) and the Help Center / Guide\n(articles, sections, categories, translations, labels, content tags, segments,\nattachments). Talk, Explore and Sell are out of scope.\n\n**Do I need a Zendesk admin API key?**\nNo, and the server doesn't support one. Each user authenticates with their own\ncredentials and the server acts with exactly their permissions\n([why](#what-this-server-does-not-do)).\n\n**Is it safe to run via `npx`?**\nReleases are published from CI via npm Trusted Publishing (OIDC), so each version\ncarries a build provenance attestation you can verify on its\n[npm page](https://www.npmjs.com/package/@fruggr/zendesk-mcp-server). No secrets\nare ever logged by the server.\n\n## Contributing\n\nPull requests are welcome, AI-assisted ones included, as long as the human\nauthor has read and validated every line. The guide, the author checklist and the\nreview workflow are in **[CONTRIBUTING.md](CONTRIBUTING.md)**.\n\nVersions follow [SemVer](https://semver.org/) and are released automatically from\n[Conventional Commits](https://www.conventionalcommits.org/); the history is in\n[`CHANGELOG.md`](CHANGELOG.md).\n\n## Inspiration & related projects\n\nThis project was built with reference to:\n- The official [Zendesk API documentation](https://developer.zendesk.com/api-reference/)\n- [mattcoatsworth/zendesk-mcp-server](https://github.com/mattcoatsworth/zendesk-mcp-server)\n- [koundinya/zd-mcp-server](https://github.com/koundinya/zd-mcp-server)\n\n## License\n\n[MIT](LICENSE)\n\n---\n\n> Built and maintained by [Digital4better](https://digital4better.com) for the [Fruggr](https://www.fruggr.io) project.\n",
  "bytes": 13190,
  "sha": "3a9b1086de10904e7b53bd6e1a17a269a4a6ce720247c2a455654dc6bd3f5605",
  "repo_slug": "fruggr/zendesk-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_fruggr_zendesk_mcp_server_a4095443/readme"
}