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

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

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>

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:

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

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

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

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:

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

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