Servidor MCP Zendesk com OAuth por Usuário
fruggr/zendesk-mcp-server
Zendesk Support & Help Center via MCP com OAuth por usuário, sem chaves compartilhadas
Ver no GitHubUm servidor MCP que integra LLMs com as APIs do Zendesk Support & Help Center usando autenticação OAuth 2.1 PKCE por usuário. Oferece controle fino de ferramentas, edição de artigos por seção, modo somente leitura e zero dependências de runtime além do SDK MCP. Ideal para assistentes que precisam gerenciar tickets e conteúdo respeitando permissões individuais, sem usar chaves compartilhadas.
Instalação
npx convez-ai fruggr/zendesk-mcp-server1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Ler e fazer triage de tickets Zendesk com permissões do próprio usuário
- Editar artigos do Help Center seção por seção, reduzindo tokens
- Criar assistentes com acesso restrito (somente leitura) a dados Zendesk
- Integrar Zendesk em Claude Desktop, Cursor ou VS Code via stdio
Veredito

Solução de integração robusta e well-engineered para Zendesk. A abordagem per-user OAuth é um diferencial real em relação a integrações convencionais com chaves compartilhadas, trazendo segurança e conformidade. Recomendado para times que precisam de automação de suporte com controle de acesso granular.
README
A tradução para o português deste README ainda está na fila.
Zendesk MCP Server
A Model Context Protocol (MCP) server that connects LLMs to the Zendesk Support & Help Center APIs — with per-user OAuth 2.1 PKCE authentication and fine-grained tool visibility controls.
Why this server?
Most Zendesk integrations use a shared admin API key, giving every user full access to every ticket. This server takes a different approach:
- Per-user authentication — Each user authenticates with their own Zendesk credentials via OAuth 2.1 PKCE. No shared admin key, no elevated privileges. The LLM sees exactly what the user is allowed to see.
- Context-friendly tool modes — Expose 37 individual tools, 3 namespace proxies, or a single unified tool. Choose the mode that fits your LLM's context budget.
- 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 LLM. Reduces tokens by 10–100× on targeted edits.
- Read-only mode — Restrict the server to read operations only, ideal for assistants that should never modify data.
- Zero runtime dependencies beyond the MCP SDK — Built on
@modelcontextprotocol/sdkandzod. No Express, no heavyweight frameworks.
Built and maintained by Digital4better for the Fruggr project.
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.
Look elsewhere when:
- You need Zendesk products outside Support & Guide (e.g. Talk, Explore analytics, Sell) — those endpoints aren't covered.
- You want a hosted/remote HTTP server: this one speaks stdio and runs next to the client.
- You need a single shared service account for all users — that's the opposite of this server's per-user OAuth model (use API-token auth if you must, but one identity then applies to everyone).
Tool modes
The server registers tools in one of three modes, controlled by --mode:
| Mode | Tools exposed | Best for |
|---|---|---|
all | 37 individual tools (get_ticket, search_articles, ...) | Clients with good tool selection, full granularity |
namespace (default) | 3 proxy tools (zendesk_tickets, zendesk_help_center, zendesk_users) | Balanced context usage, grouped operations |
single | 1 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
singlemode is particularly useful for models with limited tool slots — one tool handles all 36 operations.
Scoping the surface
--namespace and --read-only apply to every mode (including the default namespace mode) — they filter tools before the proxies are built, so the description of each proxy reflects only the operations that survive the filters. Combine them to register a focused surface:
# Only the Help Center proxy, only read-only operations
zendesk-mcp-server acme --namespace help_center --read-only
# Only the Tickets proxy (read + write)
zendesk-mcp-server acme --namespace tickets
--namespace is repeatable. --tool is also available for cherry-picking individual operations but forces --mode all.
Available tools
| Tool | Description | Mode |
|---|---|---|
get_ticket | Retrieve a ticket by ID with optional comments | read |
get_ticket_attachments | Download ticket attachments (images as base64, others as references) | read |
search_tickets | Search tickets using Zendesk query syntax | read |
list_tickets | List tickets with cursor-based pagination | read |
get_linked_incidents | Get incidents linked to a problem ticket | read |
create_ticket | Create a new ticket with subject, description, priority, tags... | write |
update_ticket | Update ticket status, priority, assignee, tags, custom fields | write |
add_private_note | Add an internal note (not visible to requester) | write |
add_public_comment | Add a public comment (visible to requester) | write |
manage_tags | Add or remove tags on a ticket | write |
| Tool | Description | Mode |
|---|---|---|
search_articles | Full-text search across Help Center articles | read |
get_article | Retrieve article by ID with full HTML body | read |
get_article_outline | Compact outline of an article (sections + available translations) | read |
get_article_section | Retrieve a single section (html or markdown) | read |
list_categories | List all Help Center categories | read |
list_sections | List sections, optionally filtered by category | read |
list_articles | List articles with sorting and translation info | read |
list_article_translations | List available translations for an article | read |
list_article_attachments | List attachments on an article | read |
list_permission_groups | List Guide permission groups (needed to create articles) | read |
list_content_tags | List Guide content tags (end-user visible) | read |
list_labels | List article labels (search ranking, not user-visible) | read |
list_user_segments | List user segments (article visibility) | read |
compare_translations | Section-level diff between two locales of an article | read |
create_article | Create a new article in a section | write |
update_article | Update article metadata (draft, labels, tags, visibility, section, sort position) | write |
create_article_translation | Create a translation for an article | write |
update_article_translation | Update an article's translation (full body) | write |
update_article_section | Replace a single section of an article | write |
create_content_tag | Create a new Guide content tag | write |
create_article_attachment | Upload an attachment to an article | write |
| Tool | Description | Mode |
|---|---|---|
get_current_user | Get the authenticated user (verify identity) | read |
search_users | Search users by name, email, or query syntax | read |
get_user | Retrieve a user by ID | read |
get_organization | Retrieve an organization by ID | read |
list_organizations | List all organizations with pagination | read |
| Tool | Description | Mode |
|---|---|---|
search | Unified search across tickets, users, and organizations | read |
Prerequisites
- Node.js >= 20 (runtime — declared in
package.json#engines.node) - A Zendesk instance (Support or Suite)
Contributors and maintainers run the toolchain on a newer Node + pnpm — see Development.
Installation
# Run without installing
npx -y @fruggr/zendesk-mcp-server <your-subdomain>
Or install globally:
npm install -g @fruggr/zendesk-mcp-server
zendesk-mcp-server <your-subdomain>
Or clone and run locally:
git clone https://github.com/fruggr/zendesk-mcp-server.git
cd zendesk-mcp-server
pnpm install
pnpm build
node dist/index.js <your-subdomain>
Or run a development branch directly from GitHub (handy for testing PRs without publishing to npm) — the prepare script builds the package automatically on install:
# Latest main
npx -y github:fruggr/zendesk-mcp-server <your-subdomain>
# A specific branch / tag / commit
npx -y github:fruggr/zendesk-mcp-server#my-feature-branch <your-subdomain>
Authentication
The server supports two authentication methods:
Option A: OAuth 2.1 PKCE (recommended)
No API key needed. Each user authenticates via their browser on the first tool call.
Zendesk setup:
- Go to Admin Center > Apps and integrations > APIs > OAuth Clients
- Create a public client:
- Identifier:
<your-subdomain>_zendesk(or setZENDESK_OAUTH_CLIENT_ID) - Redirect URL:
http://localhost:27439/callback(change the port to matchZENDESK_OAUTH_CALLBACK_PORT/--callback-portif you override it; Zendesk accepts several redirect URLs, one per line)
- Identifier:
Run:
zendesk-mcp-server <your-subdomain>
On the first tool call, the server starts the sign-in flow: it opens a browser window and returns a tool message containing the authorize URL. The call does not block waiting for sign-in — authenticate in the browser (or open the URL manually if it didn't open), then retry the request.
Once authenticated, the token is persisted to disk (one owner-only 0600
file per subdomain in your OS config dir —
%APPDATA%\fruggr\zendesk-mcp-server\<subdomain>.json on Windows,
${XDG_CONFIG_HOME:-~/.config}/fruggr/zendesk-mcp-server/<subdomain>.json
elsewhere; override the path with ZENDESK_TOKEN_FILE). It is reused across restarts, so you don't
re-authenticate every time the MCP client respawns the server. If the Zendesk
OAuth client has token expiration enabled, the stored refresh token is used to
renew access silently; only an expired/invalid refresh token triggers a new
browser sign-in.
Port conflict? If port
27439is already in use the first tool call returns a clear error telling you to setZENDESK_OAUTH_CALLBACK_PORT(or--callback-port) to a free port — remember to register the matchinghttp://localhost:<port>/callbackredirect URL in your Zendesk OAuth client.
Option B: API token
For headless/CI environments or quick testing.
Zendesk setup:
- Go to Admin Center > Apps and integrations > APIs > Zendesk API
- Enable Token Access, create a token
Run:
ZENDESK_EMAIL=you@example.com ZENDESK_API_TOKEN=dneib123... \
zendesk-mcp-server <your-subdomain>
Configuration
MCP client configuration
Add to your claude_desktop_config.json:
{
"mcpServers": {
"zendesk": {
"command": "npx",
"args": ["-y", "@fruggr/zendesk-mcp-server", "<your-subdomain>", "--mode", "single"],
"env": {
"ZENDESK_EMAIL": "you@example.com",
"ZENDESK_API_TOKEN": "your-api-token"
}
}
}
}
claude mcp add zendesk -- npx -y @fruggr/zendesk-mcp-server <your-subdomain> --mode single
For API token auth, set the env vars before launching Claude Code or add them to your shell profile.
Add to your .vscode/mcp.json:
{
"servers": {
"zendesk": {
"command": "npx",
"args": ["-y", "@fruggr/zendesk-mcp-server", "<your-subdomain>", "--mode", "single"],
"env": {
"ZENDESK_EMAIL": "you@example.com",
"ZENDESK_API_TOKEN": "your-api-token"
}
}
}
}
CLI reference
zendesk-mcp-server <subdomain> [options]
Options:
--mode <mode> single | namespace (default) | all
--namespace <ns> Filter by namespace (repeatable): tickets, help_center, users
--tool <name> Filter by tool name (repeatable, forces --mode all)
--read-only Only expose read operations
--log-level <level> debug | info (default) | warn | error
--callback-port <port> Local OAuth callback port (default 27439)
--namespace and --read-only are applied before the proxies are registered, so they narrow the surface in every mode — in the default namespace mode, --namespace help_center registers a single proxy (zendesk_help_center) instead of three.
Examples:
# Single tool mode — minimal context, all 37 operations in one tool
zendesk-mcp-server acme --mode single
# Read-only tickets only
zendesk-mcp-server acme --read-only --namespace tickets
# Cherry-pick specific tools
zendesk-mcp-server acme --tool get_ticket --tool search_tickets --tool get_current_user
Environment variables
| Variable | Required | Default | Description |
|---|---|---|---|
ZENDESK_SUBDOMAIN | yes (or CLI arg) | — | Zendesk subdomain (e.g., acme for acme.zendesk.com) |
ZENDESK_OAUTH_CLIENT_ID | no | <subdomain>_zendesk | OAuth client identifier |
ZENDESK_OAUTH_CALLBACK_PORT | no | 27439 | Local port for the OAuth browser callback (also --callback-port). Must match the redirect URL registered in Zendesk. |
ZENDESK_TOKEN_FILE | no | OS config dir | Path to the persisted OAuth token file (0600). |
ZENDESK_EMAIL | for API token auth | — | Agent email for Basic auth |
ZENDESK_API_TOKEN | for API token auth | — | Zendesk API token |
LOG_LEVEL | no | info | Log verbosity (debug surfaces the full OAuth flow trace) |
If both ZENDESK_EMAIL and ZENDESK_API_TOKEN are set, the server uses API token auth. Otherwise, it uses OAuth 2.1 PKCE.
Troubleshooting
The browser doesn't open during OAuth login
The OAuth flow opens your default browser on the first tool call. The first call fails fast with a message that includes the authorize URL, so even if the browser can't open (common in sandboxed or remote desktop environments) you can open that URL manually — it's also printed to the server's stderr. Sign in, then retry the request.
To collect diagnostics, restart with LOG_LEVEL=debug. The server then emits
structured logs through two channels, so they're reachable on any MCP client:
- stderr — captured to a log file by every mainstream client.
- MCP logging notifications (
notifications/message) — surfaced by clients that support theloggingcapability.
When the browser fails to open, look for the oauth_browser_open_failed event:
it reports the underlying error, the platform, and which environment markers are
present (no secrets, tokens, or env values are ever logged).
The OAuth callback port is already in use
The sign-in flow runs a short-lived local server on port 27439 to receive the
callback. If that port is taken, the first tool call fails with a message saying
so (and logs oauth_callback_listen_failed). Pick a free port with
ZENDESK_OAUTH_CALLBACK_PORT=<port> (or --callback-port <port>), and register
the matching http://localhost:<port>/callback redirect URL in your Zendesk
OAuth client.
I have to re-authenticate every time
The OAuth token is persisted to an owner-only file in your OS config dir and
reused across restarts, so this shouldn't happen. If it does, check that the file
is writable (ZENDESK_TOKEN_FILE to relocate it) and look for
token_persist_failed in the logs.
Where each client writes the server's stderr:
| Client | Log location |
|---|---|
| Claude Desktop (macOS) | ~/Library/Logs/Claude/mcp-server-*.log |
| Claude Desktop (Windows) | %APPDATA%\Claude\logs\mcp-server-*.log |
| Claude Code | claude --debug, or the session logs |
| Cursor / VS Code / Cline | the extension's MCP output/log panel |
Development
Toolchain
| Tool | Version | Source of truth |
|---|---|---|
| Node | 24 | .nvmrc — read by nvm, fnm, mise, asdf, volta |
| pnpm | 11 | package.json#packageManager (pinned with a corepack integrity hash) |
The toolchain (Node 24 + pnpm 11) is used to build, lint, type-check and
test the project. The published package still runs on Node 20+ (see
engines.node); a dedicated CI job installs the packed tarball on Node 20
and runs the smoke test to keep that promise honest.
# Install dependencies
pnpm install
# Dev mode (auto-reload)
ZENDESK_EMAIL=you@example.com ZENDESK_API_TOKEN=xxx \
pnpm dev -- <your-subdomain> --mode all
# Build
pnpm build
# Type-check
pnpm typecheck
# Lint
pnpm check
# Tests
pnpm test
Inspiration & related projects
This project was built with reference to:
Releases & versioning
Versions follow SemVer and are calculated automatically from commit messages — no one bumps the version by hand. Every merge to main triggers semantic-release, which inspects the new Conventional Commits since the previous tag, computes the next version, updates CHANGELOG.md, publishes to npm, and creates the matching GitHub Release.
| Commit type | Resulting bump |
|---|---|
fix:, perf: | patch |
feat: | minor |
feat!:, fix!:, or a BREAKING CHANGE: footer | major |
docs:, chore:, refactor:, test:, ci:, style:, build: | no release |
FAQ
Do I need a Zendesk admin API key? No. The default OAuth 2.1 PKCE flow means each user authenticates with their own credentials and the server acts with exactly their permissions. API-token auth is available for headless/CI use (see Authentication).
Which Zendesk products are supported? Zendesk Support (tickets, users, organizations) and the Help Center / Guide (articles, sections, categories, translations, labels, content tags, segments, attachments). Talk, Explore, and Sell are out of scope.
How do I keep the model's context small?
Use --mode single (one zendesk tool) or --mode namespace (three proxies),
and --read-only to drop write operations. For big articles, the section-based
tools (get_article_outline, get_article_section, update_article_section)
let the model touch one section at a time instead of the whole HTML body.
Can I restrict it to read-only?
Yes — pass --read-only and every write tool is filtered out before the proxies
are built, in any mode.
Which Node.js version do I need?
Node.js >= 20 to run the published package (engines.node). The dev toolchain
uses a newer Node — see Development.
The OAuth browser window didn't open. What now?
The authorization URL is also printed to stderr — open it manually. Restart with
LOG_LEVEL=debug for the full flow trace. See
Troubleshooting.
Is it safe to run via npx?
Releases are published from CI via npm Trusted Publishing (OIDC), so each version
carries a build provenance attestation you can verify on its
npm page. No secrets
are ever logged by the server.
Contributing
Pull requests are welcome — including AI-assisted ones, as long as the human author has read and validated every line.
The full guide is in CONTRIBUTING.md. The short version:
- Fork and create a feature branch from
main. - Practice TDD: write the failing test first, then implement.
- Use Conventional Commits — they drive the next version bump via semantic-release.
- Make
pnpm check,pnpm typecheck, andpnpm testpass locally. - Run a Claude Code review on your diff before pushing.
- Open a PR.
Every PR is reviewed automatically by CodeRabbit in CI, on top of the author-side AI review. The project is maintained in part with Claude Code assistance; that workflow is documented in CONTRIBUTING.md.