zendesk-mcp

# zendesk-mcp

A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes Zendesk ticket read and write tools to [Claude Code](https://claude.com/claude-code) and other MCP clients.

## What it does

- Search, list (paginated), and fetch Zendesk tickets, comments, and attachments
- Create new tickets and update existing ticket fields (including group, custom status, and tags)
- Post public replies and internal notes
- Set ticket status and assign tickets to agents
- Browse and apply views and macros
- Look up users, groups, organizations, and custom statuses
- Read and write time-tracking entries
- Format a ticket as a Markdown issue draft for handoff to a tracker (GitLab, GitHub, Jira)
- Two MCP prompts (`analyze-ticket`, `draft-ticket-response`) for ticket analysis and response drafting
- (Optional) Expose Zendesk Help Center articles as an MCP resource
- (Optional) Read linked GitLab issues / MRs / commits via the [Git-Zen](https://www.zendesk.com/marketplace/apps/support/630175/git-zen-zendesk-and-gitlab-integration/) Zendesk app

## Prerequisites

- Python 3.10 or newer
- A Zendesk OAuth client. A Zendesk admin can create one at:
  `https://<your-subdomain>.zendesk.com/admin/apps-integrations/apis/zendesk-api/oauth_clients`
  Set the redirect URL to `http://localhost:8787/callback` and request scopes `read write`.

## Install

Install into a project-local virtualenv. Using a venv keeps `zendesk-mcp` and its dependencies isolated from your system Python and from other projects, and is the recommended path for everything below.

From a clone of this repository:

```bash
python3 -m venv .venv
.venv/bin/pip install --upgrade pip
.venv/bin/pip install -e .
```

For development (also installs pytest):

```bash
.venv/bin/pip install -e ".[dev]"
```

> Throughout this README, commands use the venv's binaries via `.venv/bin/...`. You can instead `source .venv/bin/activate` once per shell and drop the prefix — the result is the same.

## OAuth setup

Run the interactive setup using the venv's Python:

```bash
.venv/bin/python -m zendesk_mcp setup
```

You will be prompted for:

1. Your Zendesk subdomain (e.g. `acme` for `acme.zendesk.com`)
2. The OAuth client ID created by your admin
3. The OAuth client secret
4. (Optional) A Git-Zen integration field ID — see [Optional: Git-Zen integration](#optional-git-zen-integration)
5. (Optional) Whether to enable the Help Center knowledge base resource — see [Optional: Help Center knowledge base](#optional-help-center-knowledge-base)

The setup opens a browser for the OAuth authorization step, then writes a token to `~/.config/zendesk-mcp/config.json` (mode `0600`).

If you have no browser, the URL is printed to the terminal — open it on any device, click **Allow**, and paste the resulting redirect URL back into the prompt.

### Token expiry and refresh

Zendesk access tokens expire. OAuth clients created on or after 2026-04-30 get a
30-minute default lifetime; older clients issue non-expiring tokens unless an expiry is
requested. Setup requests a 24-hour access token and a 90-day refresh token so the
behaviour is the same either way, and the server renews the access token automatically —
before it expires, and again if Zendesk rejects a token mid-request.

To make that possible, the config file also stores `refresh_token`, `expires_at`,
`client_id`, and `client_secret` alongside the access token. Keep the file at mode `0600`;
it is the same trust level as the access token itself. If your OAuth client returns no
refresh token, setup says so and the token is used as-is.

Re-run `.venv/bin/python -m zendesk_mcp setup` when:

- the refresh token expires (90 days with no use), or
- you revoke the OAuth grant in Zendesk.

In either case the tools return `Zendesk authorization failed: ... Re-run: zendesk-mcp setup`
rather than failing opaquely.

## Register with Claude Code

Register the MCP server using the venv's Python by absolute path. Claude Code launches the server in a fresh shell that does **not** inherit your activated venv, so the absolute path is required — pointing at a bare `python` here will fail to import `zendesk_mcp`.

```bash
ZENDESK_MCP_DIR="$(pwd)"   # run this from the repo root, after install
claude mcp add --scope user zendesk -- "$ZENDESK_MCP_DIR/.venv/bin/python" -m zendesk_mcp
```

Or just inline the absolute path you want:

```bash
claude mcp add --scope user zendesk -- /absolute/path/to/zendesk-mcp/.venv/bin/python -m zendesk_mcp
```

Then add the read tools to `permissions.allow` in `~/.claude/settings.json` to avoid per-call prompts:

```json
{
  "permissions": {
    "allow": [
      "mcp__zendesk__zendesk_get_ticket",
      "mcp__zendesk__zendesk_get_tickets",
      "mcp__zendesk__zendesk_get_comments",
      "mcp__zendesk__zendesk_list_attachments",
      "mcp__zendesk__zendesk_download_attachment",
      "mcp__zendesk__zendesk_search_tickets",
      "mcp__zendesk__zendesk_ticket_to_gitlab_context",
      "mcp__zendesk__zendesk_list_views",
      "mcp__zendesk__zendesk_get_view",
      "mcp__zendesk__zendesk_get_view_tickets",
      "mcp__zendesk__zendesk_list_macros",
      "mcp__zendesk__zendesk_preview_macro",
      "mcp__zendesk__zendesk_search_users",
      "mcp__zendesk__zendesk_get_groups",
      "mcp__zendesk__zendesk_get_group_users",
      "mcp__zendesk__zendesk_get_organization",
      "mcp__zendesk__zendesk_list_custom_statuses"
    ]
  }
}
```

Write tools (`zendesk_post_comment`, `zendesk_post_internal_note`, `zendesk_set_ticket_status`, `zendesk_assign_ticket`, `zendesk_create_ticket`, `zendesk_update_ticket`, `zendesk_log_time`, `zendesk_add_tag`, `zendesk_remove_tag`, `zendesk_apply_macro`) are intentionally not in the default allow-list — Claude will prompt you per call.

## Restricting tools

Every tool is enabled by default. To narrow what a deployment can do, for example where
ticket text is written by customers and the agent should not be able to reply to them, set
either of these in `~/.config/zendesk-mcp/config.json` or in the server's environment. Values
from both are combined.

| Config key | Environment variable | Effect |
|---|---|---|
| `"read_only": true` | `ZENDESK_MCP_READ_ONLY=true` | Registers no write tools (comments, notes, status, assignment, create/update, tags, macros, time logging) |
| `"disabled_tools": ["zendesk_post_comment"]` | `ZENDESK_MCP_DISABLED_TOOLS=zendesk_post_comment,zendesk_apply_macro` | Does not register the named tools |

A disabled tool is never registered, so the model cannot see or call it. Names that match no
tool are reported on stderr.

## Tools

### Tickets

Tools that return ticket records include `channel`, the channel the ticket arrived on (Zendesk's `via.channel`: `web`, `email`, `api`, ...), or `null` when Zendesk does not say. `zendesk_get_ticket` also returns `custom_fields` as a list of `{id, value}` pairs; a field that is not set on the ticket has a `null` value.

| Tool | What it does |
|---|---|
| `zendesk_search_tickets` | Search tickets by status, priority, type, assignee, requester, tags, or keyword. Each result includes `channel` |
| `zendesk_get_tickets` | List tickets with pagination and sorting (page, per_page, sort_by, sort_order). Each ticket includes `channel` |
| `zendesk_get_ticket` | Get one ticket's metadata, including `channel` and `custom_fields` |
| `zendesk_create_ticket` | Create a new ticket (subject, description, optional priority/type/assignee_id/requester_id/tags/custom_fields) |
| `zendesk_update_ticket` | Update one or more fields on an existing ticket (status, priority, subject, type, assignee_id, requester_id, group_id, custom_status_id, tags, custom_fields, due_at) |
| `zendesk_get_comments` | Get the conversation thread on a ticket |
| `zendesk_list_attachments` | List attachments on a ticket |
| `zendesk_download_attachment` | Download an attachment to a local cache directory. The URL must be on your Zendesk host, and `dest_dir` must be inside the cache or a directory listed in `attachment_allowed_dest_dirs` in the config |
| `zendesk_ticket_to_gitlab_context` | Format a ticket and its conversation as a Markdown issue draft |
| `zendesk_post_comment` | Post a public reply on a ticket |
| `zendesk_post_internal_note` | Post an agent-only internal note on a ticket |
| `zendesk_set_ticket_status` | Set ticket status (`new`, `open`, `pending`, `hold`, `solved`, `closed`) |
| `zendesk_assign_ticket` | Assign a ticket to an agent by email or `me` |

### Tags

| Tool | What it does |
|---|---|
| `zendesk_add_tag` | Add a tag to a ticket (idempotent) |
| `zendesk_remove_tag` | Remove a tag from a ticket (idempotent) |

### Views & Macros

| Tool | What it does |
|---|---|
| `zendesk_list_views` | List all active views |
| `zendesk_get_view` | Get a view's filter conditions and execution settings |
| `zendesk_get_view_tickets` | Fetch tickets currently matching a view. Each ticket includes `channel` |
| `zendesk_list_macros` | List active macros with their actions |
| `zendesk_preview_macro` | Preview what changes a macro would make |
| `zendesk_apply_macro` | Apply a macro to a ticket (applies field changes and posts any comment) |

### Users, Groups & Organizations

| Tool | What it does |
|---|---|
| `zendesk_search_users` | Find users by name or email |
| `zendesk_get_groups` | List all active groups |
| `zendesk_get_group_users` | List the members of a group |
| `zendesk_get_organization` | Fetch an organization including custom fields |
| `zendesk_list_custom_statuses` | List all custom ticket statuses and their IDs |

### Time tracking

| Tool | What it does |
|---|---|
| `zendesk_get_time_tracking` | Read time-tracking entries for a ticket |
| `zendesk_log_time` | Log a time entry against a ticket |

### Git-Zen integration

| Tool | What it does |
|---|---|
| `zendesk_get_git_zen_links` | (Git-Zen only) Get linked GitLab issues / MRs / commits for a ticket |

## Prompts

The server exposes two MCP prompts that some clients (