@enterpret/zendesk-mcp-server

Fork of @fruggr/zendesk-mcp-server (MIT). Adds one feature: a ZENDESK_OAUTH_BEARER env mode for headless setups where an external OAuth broker (e.g. Nango) hands the access token directly to the subprocess.

All credit for the underlying server design + tool surface goes to Digital4Better.

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 38 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.

Tool modes

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

| Mode | Tools exposed | Best for | |------|--------------|----------| | all | 38 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 single mode is particularly useful for models with limited tool slots — one tool handles all 38 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 account tickets; optional brand_id filter | read | | list_tickets | List authorized account tickets across brands with cursor pagination | read | | get_linked_incidents | Get incidents linked to a problem ticket | read | | create_ticket | Create a ticket; optional brand_id assigns its brand | write | | update_ticket | Update ticket fields; optional brand_id explicitly changes its brand | 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 | |------|-------------|------| | list_brands | Discover account brands, IDs, and Help Center subdomains with cursor pagination | read | | search_articles | Search authorized articles across brands, including restricted articles; optional brand_id filter | read | | get_article | Retrieve authorized article with full HTML body; brand_id selects another Help Center | read | | get_article_outline | Compact outline of an article (sections + available translations) | read | | get_article_section | Retrieve a single section (html or markdown); omitted locale uses the article source locale | 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 account-wide Guide permission groups (needed to create articles) | read | | list_content_tags | List account-wide Guide content tags (end-user visible) | read | | list_labels | List article labels (search ranking, not user-visible) | read | | list_user_segments | List account-wide user segments (article visibility) | read | | compare_translations | Section-level diff between two locales of an article | read | | create_article | Create an article in a section; optional brand_id selects its Help Center | write | | update_article | Update article metadata; optional brand_id selects its Help Center | write | | create_article_translation | Create a translation; optional brand_id selects its Help Center | write | | update_article_translation | Update a translation (full body); optional brand_id selects its Help Center | write | | update_article_section | Replace one article section; optional brand_id selects its Help Center | write | | create_content_tag | Create an account-wide Guide content tag | write | | create_article_attachment | Upload an article attachment; optional brand_id selects its Help Center | write |

Private/restricted Help Center articles

Help Center reads use the connected user's Zendesk permissions, including restricted articles that user can access. No additional OAuth scope is needed beyond read; reconnecting does not change the user's Guide permissions.

Help Centers are brand-specific. search_articles searches across authorized brands by default (multibrand: true). Use multibrand: false to search only the installed brand, or brand_id to search one specific brand. Search results include article URLs so you can identify their Help Center.

For an article or section on another brand, call list_brands, match its subdomain or custom domain to the article URL, and pass that brand_id to subsequent reads and writes. The connector resolves the brand through the authenticated account before sending the same token to its Zendesk subdomain; callers cannot supply an arbitrary host. Re-send brand_id on each paginated request. All numeric Zendesk resource IDs (fields ending in _id, plus attachment IDs and custom-field IDs) accept either a positive safe integer or its decimal string representation. The connector converts decimal strings to numbers before calling Zendesk and rejects other strings. This does not change which resources the connected user can access. String-valued content-tag IDs, section indexes, and pagination parameters keep their existing input types. list_brands accepts page_size and the cursor returned by its previous response; it does not use the article-search page/per_page parameters.

{"operation":"search_articles","params":{"query":"internal SOP"}}
{"operation":"list_brands","params":{}}
{"operation":"get_article","params":{"article_id":"5100","brand_id":"42"}}
{"operation":"list_articles","params":{"section_id":600,"brand_id":42}}

All brand-specific Help Center reads and writes support brand_id. It selects the target Help Center, not a field written into an article or translation. Omitting it preserves installed-subdomain behavior (except article search, which searches all authorized brands by default). Writes require the connected user's existing edit permissions and a write-capable token. Zendesk permission errors are returned directly; brand selection does not grant additional access.

Brand scope across every tool

The connection subdomain identifies the account for authentication; it is not an account-wide brand restriction. Account-level calls stay on that host and use Zendesk's native account permissions. They are not repeated across brands. list_brands belongs to help_center in every mode. When using namespace filters, include both --namespace tickets --namespace help_center to make brand discovery available alongside ticket operations. Without filters, all modes expose it (zendesk_help_center in namespace mode).

| Tools | Brand behavior | |-------|----------------| | get_article, get_article_outline, get_article_section, list_categories, list_sections, list_articles, list_article_translations, list_article_attachments, list_labels, compare_translations | Optional brand_id selects the Help Center host; use the same brand on every related read and pagination request | | create_article, update_article, create_article_translation, update_article_translation, update_article_section, create_article_attachment | Same optional brand_id routing, including preparatory reads; no automatic retries or writes to other brands | | search_articles | Native multibrand search by default; optional brand_id narrows to one brand and takes precedence over multibrand | | search_tickets | Account-wide search by default; optional brand_id adds a brand:<id> ticket search filter. Use either brand_id or brand: query filters, not both | | create_ticket, update_ticket | Account host; optional brand_id assigns/changes the ticket's brand via the ticket payload. Omitted: Zendesk's default creation behavior / preserves the existing brand on update | | get_ticket, get_ticket_attachments, list_tickets, get_linked_incidents, add_private_note, add_public_comment, manage_tags | Account-level ticket IDs/listing; no brand routing needed. Notes, comments, and tags do not change a ticket's brand | | get_current_user, search_users, get_user, get_organization, list_organizations, search | Account-wide users/organizations and unified search. Use type:ticket brand:<id> in unified search to filter tickets, not shared users/organizations | | list_brands, list_permission_groups, list_content_tags, create_content_tag, list_user_segments | Account-wide discovery/shared configuration; no Help Center brand selection needed |

Ticket reads and search results show brand_id when Zendesk supplies it. All tools reject unknown parameters, including a misspelled brandId. Account-wide operations without a brand_id parameter reject an unsupported brand filter rather than silently ignoring it. Use search_tickets for brand-filtered ticket listing.

For protected ticket image URLs on another Zendesk brand, the connector resolves the ticket's brand_id through the account Brands API before sending credentials to that exact HTTPS origin. Historical ticket brands may be inactive and do not need a Help Center. Operations routed to a brand's Help Center still require an active brand with a Help Center; article search uses Zendesk's account-level search filters. Unrelated attachment origins receive no credentials. If the ticket/brand lookup fails, foreign image URLs are attempted without credentials, so public images remain available and protected images still require authorization. Failed downloads remain text references, as before. The ticket/brand lookup is reused within that attachment call, not cached across users or calls. When supplying attachment_ids, use IDs from the specified ticket_id; the existing direct-ID lookup does not verify ticket membership. A mismatched brand host is not authenticated with the selected ticket's credentials.

API contracts: Help Center search, article visibility, and account brands. Account-level contracts: tickets, ticket brand search, permission groups, shared user segments, and shared content tags.

| 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:

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:3000/callback

Run:

zendesk-mcp-server <your-subdomain>

On the first tool call, a browser window opens for the user to authenticate. The token is cached in memory for the session.

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:

[email protected] 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": "[email protected]",
        "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": "[email protected]",
        "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

--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 38 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_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 |

If both ZENDESK_EMAIL and ZENDESK_API_TOKEN are set, the server uses API token auth. Otherwise, it uses OAuth 2.1 PKCE.

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)
[email protected] 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:

• The official Zendesk API documentation
• mattcoatsworth/zendesk-mcp-server
• koundinya/zd-mcp-server

Releases & versioning

Versions follow SemVer and are calculated automatically from commit messages — no one bumps the version by hand. Every push to this fork's default branch, master, triggers semantic-release, which inspects the new Conventional Commits since the previous tag, computes the next version, updates CHANGELOG.md, publishes @enterpret/zendesk-mcp-server to npm, and creates the matching GitHub Release. The one-time npm publisher and release-history prerequisites are in release automation.

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

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 master.
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