Content
# zendesk-ops-mcp
An MCP server that provides operational tooling over the Zendesk Support API — ticket triage, SLA monitoring, agent workload analysis, and system health audits. Built for use with [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or Claude Desktop, it gives support ops teams a conversational interface to automate the manual toil of managing Zendesk workflows.
## Quick Start
```bash
git clone https://github.com/avg-ape/zendesk-ops-mcp.git
cd zendesk-ops-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```
Configure your Zendesk credentials:
```bash
cp .env.example .env
# Edit .env with your subdomain, email, and API token
```
You can get a free Zendesk trial at [zendesk.com/register](https://www.zendesk.com/register/). Enable API tokens in Admin Center > Apps & Integrations > APIs.
### Use with Claude Code
Add to your Claude Code MCP config (`~/.claude/settings.json`):
```json
{
"mcpServers": {
"zendesk-ops": {
"command": "/path/to/zendesk-ops-mcp/.venv/bin/python",
"args": ["-m", "zendesk_ops_mcp.server"],
"env": {
"ZENDESK_SUBDOMAIN": "your-subdomain",
"ZENDESK_EMAIL": "your-email@example.com",
"ZENDESK_API_TOKEN": "your-api-token"
}
}
}
}
```
Then ask Claude things like:
- "Triage open tickets — what's missing assignees or priorities?"
- "Show me tickets that have gone stale in the last 12 hours"
- "What's the CSAT score over the last 30 days, broken down by agent?"
- "Audit our macros — are there any duplicates or unused ones?"
- "Which agents are overloaded right now?"
## Tools
| Tool | Description |
|------|-------------|
| `ticket_triage` | Find tickets missing assignees, groups, or priorities |
| `stale_ticket_report` | Tickets with no update in N hours, grouped by group/priority |
| `bulk_tag_tickets` | Tag tickets matching a search query (dry-run by default) |
| `bulk_close_tickets` | Close old solved/pending tickets (dry-run by default) |
| `sla_breach_report` | Tickets breaching or approaching SLA targets |
| `csat_summary` | Satisfaction scores over a period, by agent |
| `response_time_analysis` | First-response and resolution time averages |
| `agent_workload` | Open tickets per agent with priority breakdown |
| `group_distribution` | Ticket volume and status breakdown across groups |
| `macro_audit` | Find unused or duplicate macros |
| `trigger_review` | Audit active triggers and automations |
## Architecture
**Zendesk Client (`zendesk_client.py`):** Async HTTP client built on `httpx` with Basic auth (API token). Handles both offset pagination (`next_page`) and cursor pagination for search endpoints. Rate limit tracking via `X-RateLimit-Remaining` headers.
**Pydantic Models (`models.py`):** All tool outputs are typed Pydantic models with human-readable `__str__` methods. Claude gets structured data to reason about, not raw JSON.
**Dual Pagination:** Zendesk uses offset pagination for list endpoints (`/api/v2/tickets.json`) and search-specific pagination. The client handles both transparently via `get_all()` and `search()` methods.
## Development
```bash
# Install with dev dependencies
pip install -e ".[dev]"
# Run unit tests
pytest tests/ -v
# Run integration tests (requires Zendesk credentials)
pytest tests/ -v --integration
```
## License
MIT
