@lincolnminto/zendesk-mcp-server 2.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Digital4Better
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,309 @@
1
+ # Zendesk MCP Server
2
+
3
+ [![npm version](https://img.shields.io/npm/v/@lincolnminto/zendesk-mcp-server?logo=npm&color=cb3837)](https://www.npmjs.com/package/@lincolnminto/zendesk-mcp-server)
4
+ [![License: MIT](https://img.shields.io/npm/l/@lincolnminto/zendesk-mcp-server?color=blue)](LICENSE)
5
+ [![Node.js](https://img.shields.io/node/v/@lincolnminto/zendesk-mcp-server?logo=nodedotjs&logoColor=white&color=339933)](https://nodejs.org)
6
+
7
+ A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that
8
+ puts Zendesk inside your AI assistant. It finds answers in the Help Center;
9
+ drafts, updates and translates articles while keeping the languages in sync; and
10
+ handles Support tickets end to end, comments, triage and image attachments
11
+ included. It all happens in plain language, without switching apps.
12
+
13
+ It does roughly what the
14
+ [Zendesk agent for Microsoft 365 Copilot](https://support.zendesk.com/hc/en-us/articles/9958331458458-Using-the-Zendesk-agent-in-Microsoft-365-Copilot)
15
+ does, minus the tie to one vendor: it drops into any MCP client (Claude Desktop,
16
+ Claude Code, Cursor, VS Code, and the rest). And it always acts with each user's
17
+ own Zendesk permissions, never a shared admin key.
18
+
19
+ ## What your assistant can do
20
+
21
+ Ask in natural language; the assistant works out the context and the intent,
22
+ then calls the right tools on your behalf.
23
+
24
+ - Find answers in the Help Center. "How do I request a software license?" or
25
+ "what's the time-off policy?" surfaces the right article, matched by meaning
26
+ rather than by keyword.
27
+ - Create, view and update tickets without leaving the conversation: open a
28
+ ticket, check its status, add a public reply or an internal note, change the
29
+ priority or the assignee, mark it solved.
30
+ - Summarize a ticket for a report or a quick decision. The assistant pulls the
31
+ details and the full comment thread and gives you the gist in a sentence.
32
+ - Read the screenshots and photos attached to a ticket. Error dialogs, UI
33
+ captures and product photos are handed to your assistant's own model as
34
+ images, so it can describe them or act on what they show.
35
+ - Search and triage your queue in plain language: "show me my open tickets about
36
+ billing from this week."
37
+ - Draft and maintain knowledge-base articles. You can write a new one, or revise
38
+ a large one a single section at a time, so the whole HTML body never has to
39
+ round-trip through the model.
40
+
41
+ ## Why this server
42
+
43
+ Most Zendesk integrations run on a shared admin API key, which hands every user
44
+ full access to every ticket, and bolt on a fixed set of tools. This one is built
45
+ differently.
46
+
47
+ - Per-user authentication by default. Both transports default to OAuth 2.1
48
+ PKCE: each user signs in with their own Zendesk credentials, so the assistant
49
+ sees and touches exactly what that person is allowed to, the same scoping you
50
+ get by signing into Zendesk directly. A static API-token escape hatch is
51
+ available for stdio-only CI / headless contexts; HTTP accepts only OAuth
52
+ ([why](#what-this-server-does-not-do)).
53
+ - Section-based article editing. For large Help Center articles, read and
54
+ rewrite one section at a time (parsed by `h1`/`h2`/`h3` headings) instead of
55
+ shuffling the full HTML body through the assistant. On a targeted edit that
56
+ cuts tokens by a factor of 10 to 100.
57
+ - Native multimodal attachments. Ticket images come back as native MCP image
58
+ content, so the client's own model (Claude, GPT, Gemini, whichever) sees the
59
+ pixels directly. No server-side vision model, no extra API key, and nothing
60
+ tying you to one provider. Non-image attachments come back as text references,
61
+ and both image caps are configurable.
62
+ - A tool surface you can cap. Expose every operation as its own tool, group them
63
+ into namespace proxies, or collapse everything into a single unified tool. You
64
+ can also filter by namespace or down to read-only operations, so each context
65
+ loads only the surface it needs (see [Tool surface](#tool-surface)).
66
+ - Two deployment shapes, same auth story. Run it on your laptop as a stdio MCP
67
+ server, or deploy it as a private remote MCP server reached over HTTP, with one
68
+ Zendesk session per request and each client carrying its own user's token.
69
+ - A lean stack: the official `@modelcontextprotocol/sdk` plus `zod`, speaking to
70
+ the Zendesk Support and Help Center (Guide) APIs.
71
+
72
+ Look elsewhere when:
73
+
74
+ - You need Zendesk products outside Support and Guide (Talk, Explore analytics,
75
+ Sell). Those endpoints aren't covered.
76
+ - You need a single shared service account for a multi-user or remote
77
+ deployment. This server refuses that by design (the API-token escape hatch is
78
+ stdio-only CI, not a way to turn this into a shared backend — see below).
79
+
80
+ ## What this server does *not* do
81
+
82
+ There is no shared or HTTP-wide API-token authentication. Both transports
83
+ default to OAuth 2.1 PKCE, and HTTP accepts *only* that — a static API token is
84
+ refused at boot there. That is deliberate, for two reasons.
85
+
86
+ 1. **API tokens are insufficiently secure.** A Zendesk API token is a
87
+ long-lived, static, shared secret that carries the full rights of the user
88
+ who issued it. There is no per-user scoping, no short expiry, and no per-user
89
+ consent or revocation. OAuth 2.1 PKCE issues per-user, revocable tokens
90
+ instead.
91
+ 2. **API tokens don't scale.** A single static credential can't attribute
92
+ actions to individual users, and it can't be revoked granularly. It also
93
+ makes a multi-user remote deployment unsafe: over HTTP it would expose the
94
+ issuing user's rights to every caller.
95
+
96
+ The one exception is **stdio, for headless/CI use**: set `ZENDESK_EMAIL` +
97
+ `ZENDESK_API_TOKEN` and the server uses Basic auth instead of starting the
98
+ OAuth browser flow — see [`docs/api-token-stdio.md`](docs/api-token-stdio.md).
99
+ Reason 2 still applies there in full; reason 1's "every caller" clause doesn't,
100
+ since a stdio server is one local process for one operator, with no second
101
+ caller to expose rights to.
102
+
103
+ If you need a *shared* service account, or static API-token auth over HTTP,
104
+ use one of the other Zendesk MCP servers that support it. A few are listed
105
+ under [Inspiration & related projects](#inspiration--related-projects).
106
+
107
+ ## Quick start: local (stdio)
108
+
109
+ The default shape: one developer, one Zendesk account, OAuth 2.1 PKCE in the
110
+ browser. You need **Node.js >= 20** and a **Zendesk** instance (Support or
111
+ Suite).
112
+
113
+ ### Install
114
+
115
+ ```bash
116
+ # Run without installing
117
+ npx -y @lincolnminto/zendesk-mcp-server <your-subdomain>
118
+
119
+ # Or install globally
120
+ npm install -g @lincolnminto/zendesk-mcp-server
121
+ zendesk-mcp-server <your-subdomain>
122
+ ```
123
+
124
+ Signing in needs a Zendesk OAuth client, so register one first (next section).
125
+
126
+ ### Zendesk OAuth setup
127
+
128
+ 1. Go to **Admin Center → Apps and integrations → APIs → OAuth Clients**
129
+ 2. Create a **public** client:
130
+ - **Identifier**: `<your-subdomain>_zendesk` (or set `ZENDESK_OAUTH_CLIENT_ID`)
131
+ - **Redirect URL**: `http://localhost:27439/callback` (change the port to match
132
+ `ZENDESK_OAUTH_CALLBACK_PORT` / `--callback-port` if you override it; Zendesk
133
+ accepts several redirect URLs, one per line)
134
+
135
+ On the first tool call the server starts the sign-in flow: it opens a browser
136
+ window and returns the authorize URL in a tool message. The call does not block
137
+ waiting for sign-in, so authenticate in the browser and then retry the request.
138
+ The token is persisted to an owner-only file and reused across restarts, so you
139
+ don't authenticate again every time your MCP client respawns the server (path
140
+ and overrides: [`ZENDESK_TOKEN_FILE`](docs/configuration.md#zendesk_token_file)).
141
+
142
+ > **API token escape hatch (stdio only).** For headless/CI environments where a
143
+ > browser is unavailable, set `ZENDESK_EMAIL` + `ZENDESK_API_TOKEN` (generate
144
+ > the token in **Admin Center → Apps and integrations → APIs → Zendesk API →
145
+ > Token Access**). The server then uses Basic auth instead of starting the
146
+ > OAuth flow. This mode is **refused at boot in HTTP** because a shared static
147
+ > credential would expose every caller to the issuing user's rights. Full setup:
148
+ > [`docs/api-token-stdio.md`](docs/api-token-stdio.md).
149
+
150
+ ### MCP client wiring
151
+
152
+ <details>
153
+ <summary><strong>Claude Desktop</strong></summary>
154
+
155
+ Add to your `claude_desktop_config.json`:
156
+
157
+ ```json
158
+ {
159
+ "mcpServers": {
160
+ "zendesk": {
161
+ "command": "npx",
162
+ "args": ["-y", "@lincolnminto/zendesk-mcp-server", "<your-subdomain>", "--mode", "single"]
163
+ }
164
+ }
165
+ }
166
+ ```
167
+
168
+ </details>
169
+
170
+ <details>
171
+ <summary><strong>Claude Code</strong></summary>
172
+
173
+ ```bash
174
+ claude mcp add zendesk -- npx -y @lincolnminto/zendesk-mcp-server <your-subdomain> --mode single
175
+ ```
176
+
177
+ </details>
178
+
179
+ <details>
180
+ <summary><strong>VS Code (Copilot / Continue / Cline)</strong></summary>
181
+
182
+ Add to your `.vscode/mcp.json`:
183
+
184
+ ```json
185
+ {
186
+ "servers": {
187
+ "zendesk": {
188
+ "command": "npx",
189
+ "args": ["-y", "@lincolnminto/zendesk-mcp-server", "<your-subdomain>", "--mode", "single"]
190
+ }
191
+ }
192
+ }
193
+ ```
194
+
195
+ </details>
196
+
197
+ Something not working? See [Troubleshooting](docs/troubleshooting.md).
198
+
199
+ ## Quick start: remote (HTTP)
200
+
201
+ > **Experimental.** The HTTP transport ships, but it has not yet been exercised
202
+ > end-to-end against a real Zendesk tenant from every MCP client. Local stdio is
203
+ > the supported path.
204
+
205
+ You can also deploy a private remote MCP server for **one** Zendesk account,
206
+ where every MCP client presents its **own** user's OAuth bearer in
207
+ `Authorization:` and the server never sees a shared admin key. The full guide
208
+ covers OAuth setup, `--public-url` behind a reverse proxy, per-platform config,
209
+ the discovery endpoints, MCP client wiring, CORS and what stays the operator's
210
+ job: **[docs/http-deployment.md](docs/http-deployment.md)**.
211
+
212
+ ## Tool surface
213
+
214
+ Tools are grouped into four namespaces: **Tickets**, **Help Center**, **Users &
215
+ Organizations** and **Search**. The server registers them in one of three modes,
216
+ so you can trade granularity against context budget:
217
+
218
+ - **`all`**: every operation as its own tool, for clients with good tool selection;
219
+ - **`namespace`** (default): one proxy tool per namespace, a balanced middle ground;
220
+ - **`single`**: a single `zendesk` tool, for models with limited tool slots.
221
+
222
+ Proxies take `{ "operation": "<tool_name>", "params": { … } }` and validate
223
+ `params` through the original schema. `--namespace`, `--tool` and `--read-only`
224
+ filter tools *before* the proxies are built, so each proxy describes only the
225
+ operations that survive.
226
+
227
+ Every tool with its description and its `read`/`write` mode:
228
+ **[docs/mcp-tools-reference.md](docs/mcp-tools-reference.md)**. The flags and
229
+ worked examples: **[docs/configuration.md](docs/configuration.md)**.
230
+
231
+ ## Help Center context
232
+
233
+ Beyond tools, the server hands the LLM the structure of *your* Help Center: the
234
+ active locales, the category → section tree with IDs, the visibility segments
235
+ and the permission groups. With those in hand it uses real IDs instead of
236
+ guessing or fuzzy-matching names. It all arrives through MCP-native channels,
237
+ namely the `instructions` blob sent on `initialize` plus pull-only resources for
238
+ the topology and for reading (or pinning) individual articles. The resources are
239
+ fetched with the caller's own token, and clients that don't support resources
240
+ ignore them silently.
241
+
242
+ What's exposed, what the promoted-article pre-listing costs in requests, and how
243
+ to turn each piece off: **[docs/help-center-context.md](docs/help-center-context.md)**.
244
+
245
+ ## Configuration
246
+
247
+ The complete reference for the CLI flags (`--mode`, `--namespace`,
248
+ `--read-only`, `--transport`, `--public-url`, and so on) and the environment
249
+ variables (`ZENDESK_SUBDOMAIN`, `ZENDESK_TOKEN_FILE`, `PUBLIC_URL`, the
250
+ attachment-vision caps) lives in
251
+ **[docs/configuration.md](docs/configuration.md)**. Every variable has its own
252
+ anchor, so you can deep-link a specific setting.
253
+
254
+ ## Troubleshooting
255
+
256
+ Browser not opening during OAuth login, the callback port already in use, having
257
+ to re-authenticate every time, and `Permission denied` on the Guide-admin
258
+ endpoints are covered in **[docs/troubleshooting.md](docs/troubleshooting.md)**.
259
+ Restart with `LOG_LEVEL=debug` for the full OAuth flow trace.
260
+
261
+ ## Development
262
+
263
+ Setting up the repo, the toolchain, dev mode and how to test a PR branch are
264
+ covered in **[CONTRIBUTING.md](CONTRIBUTING.md#development-setup)**. Architecture
265
+ and code-style conventions live in [`AGENTS.md`](AGENTS.md).
266
+
267
+ ## FAQ
268
+
269
+ **Which Zendesk products are supported?**
270
+ Zendesk Support (tickets, users, organizations) and the Help Center / Guide
271
+ (articles, sections, categories, translations, labels, content tags, segments,
272
+ attachments). Talk, Explore and Sell are out of scope.
273
+
274
+ **Do I need a Zendesk admin API key?**
275
+ No. Each user authenticates with their own OAuth credentials by default, and
276
+ the server acts with exactly their permissions. A static API token is only a
277
+ stdio-only CI escape hatch, never a shared or HTTP-wide credential
278
+ ([why](#what-this-server-does-not-do)).
279
+
280
+ **Is it safe to run via `npx`?**
281
+ Releases are published from CI via npm Trusted Publishing (OIDC), so each version
282
+ carries a build provenance attestation you can verify on its
283
+ [npm page](https://www.npmjs.com/package/@lincolnminto/zendesk-mcp-server). No secrets
284
+ are ever logged by the server.
285
+
286
+ ## Contributing
287
+
288
+ Pull requests are welcome, AI-assisted ones included, as long as the human
289
+ author has read and validated every line. The guide, the author checklist and the
290
+ review workflow are in **[CONTRIBUTING.md](CONTRIBUTING.md)**.
291
+
292
+ Versions follow [SemVer](https://semver.org/) and are released automatically from
293
+ [Conventional Commits](https://www.conventionalcommits.org/); the history is in
294
+ [`CHANGELOG.md`](CHANGELOG.md).
295
+
296
+ ## Inspiration & related projects
297
+
298
+ This project was built with reference to:
299
+ - The official [Zendesk API documentation](https://developer.zendesk.com/api-reference/)
300
+ - [mattcoatsworth/zendesk-mcp-server](https://github.com/mattcoatsworth/zendesk-mcp-server)
301
+ - [koundinya/zd-mcp-server](https://github.com/koundinya/zd-mcp-server)
302
+
303
+ ## License
304
+
305
+ [MIT](LICENSE)
306
+
307
+ ---
308
+
309
+ > Built and maintained by [Digital4better](https://digital4better.com) for the [Fruggr](https://www.fruggr.io) project.