mcp-server-zendesk

mcp-server-zendesk

An MCP server that gives AI assistants full access to your Zendesk instance — search tickets, manage tags, create tickets, inspect automations, and more.

Works with Kiro, Claude Code, Claude Desktop, Cursor, Windsurf, and any MCP-compatible client.

What it does

Connect your AI assistant to Zendesk and ask things like:

• "How many unsolved tickets do we have?"
• "Show me all high-priority tickets assigned to [email protected]"
• "Create a ticket for the billing team about the invoice issue"
• "Add an internal note to ticket 4521 saying we're waiting on the vendor"
• "Who solved the most tickets today?"
• "What macros do we have for password reset requests?"
• "List all automations that fire on pending tickets"

Tools (27)

Tickets

Users & Organizations

Views

Business Rules

Groups & Performance

Quick Start

1. Install

git clone https://github.com/kalchevs/zendesk-mcp.git
cd zendesk-mcp
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

2. Configure

cp .env.example .env

Edit .env — choose one authentication mode:

Option A — API Token (simple, no expiry):

ZD_SUBDOMAIN=your-company
[email protected]
ZD_API_TOKEN=your-token-here

Option B — OAuth Bearer Token (recommended for production):

ZD_SUBDOMAIN=your-company
ZD_OAUTH_ACCESS_TOKEN=your-access-token
ZD_OAUTH_REFRESH_TOKEN=your-refresh-token
ZD_OAUTH_CLIENT_ID=your-client-id
ZD_OAUTH_CLIENT_SECRET=your-client-secret

OAuth tokens are refreshed automatically when they expire (401 → refresh → retry). If only ZD_OAUTH_ACCESS_TOKEN is set without refresh credentials, the server works until the token expires.

3. Connect to your AI client

See detailed setup for each client below.

Client Setup

Kiro IDE

Option A — Stdio (local, recommended for development):

Create .kiro/settings/mcp.json in your workspace root:

{
  "mcpServers": {
    "zendesk": {
      "command": "./venv/bin/python3",
      "args": ["./mcp_server.py"],
      "autoApprove": [
        "count_tickets",
        "search_tickets",
        "get_ticket",
        "get_ticket_comments",
        "get_user",
        "search_users",
        "list_triggers",
        "list_macros",
        "list_groups"
      ]
    }
  }
}

Or copy the included example:

mkdir -p .kiro/settings
cp mcp.json.example .kiro/settings/mcp.json

Option B — SSE (remote Docker server):

{
  "mcpServers": {
    "zendesk": {
      "url": "http://localhost:8080/sse"
    }
  }
}

After saving, the server connects automatically. Check the MCP Server panel in Kiro to confirm. If it doesn't connect, use Command Palette → "MCP: Reconnect Server".

Kiro CLI

Same config file at ~/.kiro/settings/mcp.json (global) or .kiro/settings/mcp.json (workspace):

cp mcp.json.example ~/.kiro/settings/mcp.json

Then start a session:

kiro
# "How many unsolved tickets do we have?"
# "Show me tickets assigned to [email protected]"
# "Create a ticket about the login issue for [email protected]"

Claude Code

Add to your Claude Code MCP configuration (~/.claude/mcp.json or project-level):

Stdio (local):

{
  "mcpServers": {
    "zendesk": {
      "command": "/path/to/zendesk-mcp/venv/bin/python3",
      "args": ["/path/to/zendesk-mcp/mcp_server.py"]
    }
  }
}

SSE (remote/Docker):

{
  "mcpServers": {
    "zendesk": {
      "url": "http://localhost:8080/sse"
    }
  }
}

Note for Claude Code stdio: Use absolute paths since Claude Code may not run from the project directory.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "zendesk": {
      "command": "/path/to/zendesk-mcp/run_mcp.sh",
      "args": []
    }
  }
}

The run_mcp.sh wrapper auto-detects its directory, so it works regardless of Claude Desktop's working directory.

Cursor / Windsurf / Other MCP Clients

Any client that supports the MCP protocol works. Use either:

• Stdio: point to ./venv/bin/python3 with args ["./mcp_server.py"]
• SSE: connect to http://localhost:8080/sse (requires Docker or python3 mcp_server_http.py running)

Docker

Run as a remote HTTP/SSE server:

# With Docker Compose (recommended)
docker compose up -d --build

# Health check
curl http://localhost:8080/health

Then connect clients using the SSE URL:

{
  "mcpServers": {
    "zendesk": {
      "url": "http://localhost:8080/sse"
    }
  }
}

Architecture

mcp_server.py        — MCP protocol server (stdio transport)
mcp_server_http.py   — HTTP/SSE transport (for Docker/network)
tools.py             — Core ticket tools (async)
tools_extra.py       — User, org, view, trigger, macro, group tools (async)
zendesk_client.py    — Async HTTP client with retry, rate-limit handling, path allowlist
config.py            — Settings from .env via pydantic-settings

Key design decisions:

• Async-first — all tools use httpx.AsyncClient for non-blocking I/O
• Path allowlisting — only pre-approved Zendesk API endpoints can be called
• Rate limit retry — automatic backoff on 429 and 5xx errors
• Error masking — set MASK_ERRORS=true in production to hide internal details
• Lifespan management — HTTP client properly opened/closed on server start/stop

Query Syntax

All ticket search queries must include type:ticket:

type:ticket status<solved                           # All unsolved
type:ticket priority:high status:open               # High priority open
type:ticket assignee:[email protected]               # By assignee
type:ticket created>=2025-01-01 created<2025-02-01  # Date range
type:ticket tags:billing organization:ACME          # Tag + org
type:ticket "exact phrase"                          # Text search

Security

• API credentials stay in .env (gitignored)
• Supports both API token and OAuth authentication
• OAuth tokens are refreshed automatically on expiry — no manual intervention
• Path allowlist prevents access to unauthorized Zendesk endpoints
• Write tools require explicit approval (not auto-approved)
• MASK_ERRORS=true hides internal error details in production
• Docker Compose reads .env at runtime (credentials not baked into image)

Requirements

• Python 3.10+
• Zendesk account with API access
• One of:
  • API token from Zendesk Admin > Channels > API
  • OAuth access token (from authorization code or client credentials flow)

License

MIT