# 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 (e.g. Claude Desktop) surface as slash commands:

| Prompt | Argument | What it does |
|---|---|---|
| `analyze-ticket` | `ticket_id` | Asks the model to fetch the ticket and produce a summary, status/timeline, and key interaction points |
| `draft-ticket-response` | `ticket_id` | Asks the model to fetch the ticket and draft a customer-facing response (with a confirmation step before posting) |

## Optional: Git-Zen integration

If your Zendesk instance uses the [Git-Zen](https://www.zendesk.com/marketplace/apps/support/630175/git-zen-zendesk-and-gitlab-integration/) app, the `zendesk_get_git_zen_links` tool can read its custom-field payload. Find your instance's Git-Zen custom field ID under **Admin → Tickets → Fields** (it is a numeric ID), then either set it during `.venv/bin/python -m zendesk_mcp setup` or edit `~/.config/zendesk-mcp/config.json` to add:

```json
{
  "git_zen_field_id": 12345678901234
}
```

Without this configured, `zendesk_get_git_zen_links` returns a "not configured" message.

## Optional: Help Center knowledge base

If your Zendesk instance has a published Help Center, you can expose its sections and articles as the `zendesk://knowledge-base` MCP resource. The resource returns a single JSON document covering all sections and articles, cached for one hour.

This is opt-in. Enable it by either answering "y" to the prompt during `.venv/bin/python -m zendesk_mcp setup`, or by adding the following to `~/.config/zendesk-mcp/config.json`:

```json
{
  "knowledge_base_enabled": true
}
```

When the flag is absent or false, the resource is not registered, keeping the server's resource list empty for instances without a Help Center.

## Optional: downloading attachments outside the cache

`zendesk_download_attachment` writes files to `~/.cache/zendesk-mcp/attachments/<ticket_id>/` by default (configurable via `attachment_cache_dir`). The `dest_dir` argument can redirect a download elsewhere, but because attachment contents are controlled by whoever wrote the ticket, the tool only accepts a `dest_dir` inside the cache or inside a directory you have explicitly allowed. Add the directories you want to permit to `~/.config/zendesk-mcp/config.json`:

```json
{
  "attachment_allowed_dest_dirs": ["/home/me/work/support_bundles"]
}
```

Paths are resolved before the check, so `..` segments and symlinks cannot escape an allowed directory. Any `dest_dir` outside the allowed set is refused before the download starts.

The download URL itself must be an `https` URL on `<subdomain>.zendesk.com` for your configured subdomain; the tool refuses anything else so the OAuth token is never sent to another host. Archives are limited to 10,000 entries and 256 MiB unpacked, and tar members that are not regular files or directories are skipped.

## Development

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

Tests run on Python 3.10, 3.11, and 3.12 in CI (see `.github/workflows/test.yml`).

### Releasing

Bump the version in `pyproject.toml`, `mcpb/pyproject.toml` (both the version and
the `zendesk-mcp==` pin), `mcpb/manifest.json`, and `server.json` (both fields),
then push a `v*` tag. That triggers `.github/workflows/release.yml`, which publishes
to PyPI, packs the MCPB bundle, publishes `server.json` to the MCP Registry, and
cuts the GitHub release.

Check the versions agree before tagging — the release fails fast otherwise:

```bash
python3 .github/scripts/check_versions.py 0.1.5
```

## License

[Apache-2.0](LICENSE)

<!-- mcp-name: io.github.michaelrice/zendesk-mcp -->