Zendesk MCP Server

A read-only Model Context Protocol server for Zendesk admin consultants. It feeds an AI agent live context about a customer's Zendesk instance so you can audit, untangle and solutionise faster.

Why this exists

Zendesk admin consultancy is a solutionising job. A client states a goal ("auto-assign tickets to agents"), you pick an approach ("omnichannel routing"), and then you have to work out how it would actually fit in their specific instance: what already exists, what would conflict, what's missing. Doing that across many clients means digging through Admin Center, across triggers, automations, macros, ticket forms, custom fields, routing, SLAs, brands, schedules, custom roles and webhooks, for every single one.

The questions that come up daily ("which triggers apply tag X", "which forms reference custom field Y", "which triggers conflict with each other") have no native equivalent in the Zendesk UI or API. This server gives an AI agent the audit-grade reads, relational queries and pre-baked composites it needs to make a client's instance legible in seconds. The server exposes state, the agent does the reasoning, and you stay the architect.

Related MCP server: mcp-server-zendesk

What it does (v1)

• Read-only by design. v1 is deliberately reads only, no writes anywhere in the surface. Pointing an agent at a client's production instance is a lot easier to sign off on when the worst it can do is read. Writes are a separate, later conversation, once the read patterns have settled.

• Multi-instance by design. One server process, any number of configured Zendesk instances, sticky-session switching with a per-call override. No more swapping .env files between clients.

• Three layers of tools.

  • Primitives (~70): list_* and get_* for triggers, automations, macros, views, ticket fields, ticket forms, custom statuses, brands, custom roles, schedules, SLA policies, webhooks, dynamic content, routing attributes, skills, audit logs and the rest of the admin surface.

  • Analyzers: find_triggers_by_tag, find_triggers_by_field, find_trigger_conflicts, find_field_usage, find_form_usage, find_group_usage, list_tags_in_use, find_unused. Each match carries a why_matched breadcrumb, so the agent's reasoning stays auditable.

  • Audit composites: summarize_instance, audit_trigger_health, audit_tag_sprawl, audit_field_health. One-call dashboards, built for the first message of a new client engagement.

• Quiet in operation. Responses are thin by default, pagination is automatic up to 25,000 items, there's an in-memory TTL cache (5 minutes), HTTP is concurrency-capped with transparent 429 retry, and rate limiting is plan-aware and per-endpoint (Team, Growth, Professional, Enterprise and Enterprise Plus, with separate budgets for search and incremental endpoints, since Zendesk caps those more tightly than the overall budget). Responses come back as structured envelopes with stable error codes. The user never sees a 429, a cache miss or a paginated cursor, and neither does your client's own staff.

• PII-safe by default. A per-instance scope controls which tools the agent can invoke. config (the production default) hides every tool that touches a ticket, user or organization, so customer content cannot reach the agent. config_plus_audits adds back the forensic-debugging tools (get_ticket_audits, get_ticket_metrics), with comment bodies redacted in audit responses. full exposes everything, and is the sandbox default.

Quick start (macOS)

# 1. Clone and install
git clone https://github.com/rlowndes9/zendesk-mcp-server.git
cd zendesk-mcp-server
npm install

# 2. Create the config directory
mkdir -p ~/.config/zendesk-mcp

# 3. Write your instances.json (replace the placeholders).
#    `plan`  - the client's Zendesk Suite tier. Drives proactive throttling
#              to 25% of plan limits. team | growth | professional |
#              enterprise | enterprise_plus. Always set this on production.
#    `scope` - which tools are exposed for this instance. Recommended:
#              "config"             - config audit only, no PII (default for prod)
#              "config_plus_audits" - adds get_ticket_audits + get_ticket_metrics,
#                                     with comment bodies redacted (forensic debugging)
#              "full"               - everything (default for sandbox)
cat > ~/.config/zendesk-mcp/instances.json <<'EOF'
{
  "instances": {
    "acme": {
      "subdomain": "acme",
      "email": "you@example.com",
      "token": "your-zendesk-api-token",
      "env": "prod",
      "plan": "enterprise_plus",
      "scope": "config_plus_audits"
    }
  }
}
EOF

# 4. Lock the file down (it holds a live API token)
chmod 600 ~/.config/zendesk-mcp/instances.json

# 5. Smoke test
npm run inspect

Open the Inspector URL it prints, click Tools, then run list_instances, set_instance({ name: "acme" }) and list_triggers. Full troubleshooting lives in docs/RUNNING.md.

Quick start (Windows, PowerShell)

# 1. Clone and install
git clone https://github.com/rlowndes9/zendesk-mcp-server.git
cd zendesk-mcp-server
npm install

# 2. Create the config directory
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.config\zendesk-mcp"

# 3. Write your instances.json (replace the placeholders, then paste the whole block).
#    `plan`  - the client's Zendesk Suite tier. Drives proactive throttling
#              to 25% of plan limits. team | growth | professional |
#              enterprise | enterprise_plus. Always set this on production.
#    `scope` - which tools are exposed for this instance. Recommended:
#              "config"             - config audit only, no PII (default for prod)
#              "config_plus_audits" - adds get_ticket_audits + get_ticket_metrics,
#                                     with comment bodies redacted (forensic debugging)
#              "full"               - everything (default for sandbox)
@'
{
  "instances": {
    "acme": {
      "subdomain": "acme",
      "email": "you@example.com",
      "token": "your-zendesk-api-token",
      "env": "prod",
      "plan": "enterprise_plus",
      "scope": "config_plus_audits"
    }
  }
}
'@ | Set-Content -Path "$env:USERPROFILE\.config\zendesk-mcp\instances.json" -Encoding utf8NoBOM

# 4. Lock the file down (it holds a live API token)
icacls "$env:USERPROFILE\.config\zendesk-mcp\instances.json" /inheritance:r /grant:r "$($env:USERNAME):(R,W)"

# 5. Smoke test
npm run inspect

Open the Inspector URL it prints, click Tools, then run list_instances, set_instance({ name: "acme" }) and list_triggers. Full troubleshooting lives in docs/RUNNING.md.

Note. Set-Content -Encoding utf8NoBOM needs PowerShell 6 or later. On Windows PowerShell 5.1 (the default on older Windows installs), use [System.IO.File]::WriteAllText("$env:USERPROFILE\.config\zendesk-mcp\instances.json", $jsonContent, [System.Text.UTF8Encoding]::new($false)) instead, because Node's JSON.parse rejects files that carry a UTF-8 BOM.

Adding more clients later

Add another key under instances in the same file. Restart the server, or call refresh_instance if you've only rotated an existing token, since the file is loaded once at startup.

Worked example: omnichannel routing

This is the canonical workflow. A consultant picks up Acme and needs to work out whether a routing change is safe:

You: Client wants agents auto-assigned tickets. I'm thinking omnichannel routing. What's the lay of the land in Acme?

Agent: calls set_instance({ name: "acme" }), then summarize_instance, audit_trigger_health, find_triggers_by_field({ field: "assignee_id" }), find_triggers_by_field({ field: "group_id" }), list_routing_attributes and list_skills

Agent: Acme has 247 triggers, 12 of which currently assign agents directly (5 by group, 7 by user). Three pairs conflict on overwrite order. Routing attributes are configured but no skills are assigned to agents yet. If we switch to omnichannel queues, the 12 trigger-based assignments will need deactivating or rewriting. Here's the list, with positions and why each one matched...

From there it's a normal design conversation. The agent has the facts, you have the judgement.

More worked examples (first-touch on a new client, "is it safe to delete this custom field?", post-incident "why did the macro send the ticket to the wrong group?", tag-sprawl audits, cross-instance pattern reuse) live in docs/use_case.md.

Available tools

Grouped by layer. See docs/RUNNING.md section 8 for the full surface, and npm run inspect for live introspection.

Every list response is thin by default (id, title, active and so on). Pass verbose: true for the full Zendesk payload. Every analysis result includes why_matched breadcrumbs.

Configuration

Instance credentials live in ~/.config/zendesk-mcp/instances.json on macOS and Linux, or C:\Users\<you>\.config\zendesk-mcp\instances.json on Windows (with ~/.zendesk-mcp/instances.json and C:\Users\<you>\.zendesk-mcp\instances.json as fallbacks). The key under instances is the short name you'll pass to set_instance.

{
  "instances": {
    "acme":     { "subdomain": "acme",        "email": "...", "token": "...", "env": "prod",    "plan": "enterprise_plus", "scope": "config_plus_audits" },
    "acme-sbx": { "subdomain": "acmesandbox", "email": "...", "token": "...", "env": "sandbox" },
    "globex":   { "subdomain": "globex",      "email": "...", "token": "...", "env": "prod",    "plan": "professional",    "scope": "config" },
    "smallcli": { "subdomain": "smallcli",    "email": "...", "token": "...", "env": "prod",    "plan": "team",            "scope": "config" }
  }
}

Per-instance fields:

Lock the file down, since it holds live API tokens (chmod 600 on Unix; on Windows, icacls ... /inheritance:r /grant:r "%USERNAME%:(R,W)"). The full configuration guide and troubleshooting live in docs/RUNNING.md.

Connecting to Claude Desktop

Add this to ~/Library/Application Support/Claude/claude_desktop_config.json (the macOS path; see RUNNING.md for Windows and Linux):

{
  "mcpServers": {
    "zendesk": {
      "command": "node",
      "args": ["/absolute/path/to/zendesk-mcp-server/src/index.js"]
    }
  }
}

Fully quit and relaunch Claude Desktop. Details are in docs/RUNNING.md section 5.

Connecting to Claude Code

claude mcp add zendesk node /absolute/path/to/zendesk-mcp-server/src/index.js

Details are in docs/RUNNING.md section 6.

Project status

v1 is read-only, and that's a deliberate scope decision rather than an unfinished one. The whole surface reads Zendesk config and never writes it, which keeps it safe to run against a live client instance. It's usable today for auditing and solutionising. Writes may follow in a later version once the read patterns have proven out. Bug reports and suggestions are welcome.

Architecture

• docs/PRD.md covers the design rationale and decisions.

• docs/RUNNING.md covers full setup, troubleshooting, Claude Desktop and Code wiring, and the per-plan rate-limit table.

• docs/use_case.md covers six worked workflow examples (solutionising, forensic debugging, cleanup safety checks, first-touch audits, tag-sprawl, and cross-instance comparison).

Analyzer modules under src/lib/ are pure functions over fetched corpora, so they're independently testable with no HTTP, and the test suite under test/ exercises them with hand-built fixtures.

License

Released under the MIT License.