convez.ai
MCP ServerIntegração & APIsAvançado
fruggr

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 GitHub
BomPluginScore · de 0 a 100

Um 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-server

1 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

Estrelas
15
Forks
9
Acompanhando
1
Saúde
75%
Último commit
há 2 dias
Versão
v3.11.0
Issues abertas
12
Contribuidores
5

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

Glama score npm version License: MIT Node.js Renovate enabled semantic-release

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/sdk and zod. 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:

ModeTools exposedBest for
all37 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
single1 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 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

ToolDescriptionMode
get_ticketRetrieve a ticket by ID with optional commentsread
get_ticket_attachmentsDownload ticket attachments (images as base64, others as references)read
search_ticketsSearch tickets using Zendesk query syntaxread
list_ticketsList tickets with cursor-based paginationread
get_linked_incidentsGet incidents linked to a problem ticketread
create_ticketCreate a new ticket with subject, description, priority, tags...write
update_ticketUpdate ticket status, priority, assignee, tags, custom fieldswrite
add_private_noteAdd an internal note (not visible to requester)write
add_public_commentAdd a public comment (visible to requester)write
manage_tagsAdd or remove tags on a ticketwrite
ToolDescriptionMode
search_articlesFull-text search across Help Center articlesread
get_articleRetrieve article by ID with full HTML bodyread
get_article_outlineCompact outline of an article (sections + available translations)read
get_article_sectionRetrieve a single section (html or markdown)read
list_categoriesList all Help Center categoriesread
list_sectionsList sections, optionally filtered by categoryread
list_articlesList articles with sorting and translation inforead
list_article_translationsList available translations for an articleread
list_article_attachmentsList attachments on an articleread
list_permission_groupsList Guide permission groups (needed to create articles)read
list_content_tagsList Guide content tags (end-user visible)read
list_labelsList article labels (search ranking, not user-visible)read
list_user_segmentsList user segments (article visibility)read
compare_translationsSection-level diff between two locales of an articleread
create_articleCreate a new article in a sectionwrite
update_articleUpdate article metadata (draft, labels, tags, visibility, section, sort position)write
create_article_translationCreate a translation for an articlewrite
update_article_translationUpdate an article's translation (full body)write
update_article_sectionReplace a single section of an articlewrite
create_content_tagCreate a new Guide content tagwrite
create_article_attachmentUpload an attachment to an articlewrite
ToolDescriptionMode
get_current_userGet the authenticated user (verify identity)read
search_usersSearch users by name, email, or query syntaxread
get_userRetrieve a user by IDread
get_organizationRetrieve an organization by IDread
list_organizationsList all organizations with paginationread
ToolDescriptionMode
searchUnified search across tickets, users, and organizationsread

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:

  1. Go to Admin Center > Apps and integrations > APIs > OAuth Clients
  2. Create a public client:
    • Identifier: <your-subdomain>_zendesk (or set ZENDESK_OAUTH_CLIENT_ID)
    • Redirect URL: http://localhost:27439/callback (change the port to match ZENDESK_OAUTH_CALLBACK_PORT / --callback-port if you override it; Zendesk accepts several redirect URLs, one per line)

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 27439 is already in use the first tool call returns a clear error telling you to set ZENDESK_OAUTH_CALLBACK_PORT (or --callback-port) to a free port — remember to register the matching http://localhost:<port>/callback redirect URL in your Zendesk OAuth client.

Option B: API token

For headless/CI environments or quick testing.

Zendesk setup:

  1. Go to Admin Center > Apps and integrations > APIs > Zendesk API
  2. 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

VariableRequiredDefaultDescription
ZENDESK_SUBDOMAINyes (or CLI arg)—Zendesk subdomain (e.g., acme for acme.zendesk.com)
ZENDESK_OAUTH_CLIENT_IDno<subdomain>_zendeskOAuth client identifier
ZENDESK_OAUTH_CALLBACK_PORTno27439Local port for the OAuth browser callback (also --callback-port). Must match the redirect URL registered in Zendesk.
ZENDESK_TOKEN_FILEnoOS config dirPath to the persisted OAuth token file (0600).
ZENDESK_EMAILfor API token auth—Agent email for Basic auth
ZENDESK_API_TOKENfor API token auth—Zendesk API token
LOG_LEVELnoinfoLog 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 the logging capability.

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:

ClientLog location
Claude Desktop (macOS)~/Library/Logs/Claude/mcp-server-*.log
Claude Desktop (Windows)%APPDATA%\Claude\logs\mcp-server-*.log
Claude Codeclaude --debug, or the session logs
Cursor / VS Code / Clinethe extension's MCP output/log panel

Development

Toolchain

ToolVersionSource of truth
Node24.nvmrc — read by nvm, fnm, mise, asdf, volta
pnpm11package.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 typeResulting bump
fix:, perf:patch
feat:minor
feat!:, fix!:, or a BREAKING CHANGE: footermajor
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:

  1. Fork and create a feature branch from main.
  2. Practice TDD: write the failing test first, then implement.
  3. Use Conventional Commits — they drive the next version bump via semantic-release.
  4. Make pnpm check, pnpm typecheck, and pnpm test pass locally.
  5. Run a Claude Code review on your diff before pushing.
  6. 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.

License

MIT

Ver o original no GitHub

Bom para

Relacionados