Zendesk MCP

What michaelrice/zendesk-mcp MCP server does

The michaelrice/zendesk-mcp MCP server gives an MCP client access to Zendesk ticket workflows. Read operations include searching and paginating tickets, retrieving ticket metadata and conversation threads, listing or downloading attachments, inspecting views and macros, and looking up users, groups, organizations, and custom statuses.

Write operations can create tickets, change ticket fields, post public replies or internal notes, set a ticket status, assign an agent, add or remove tags, apply macros, and record time. The server also provides a tool that formats a ticket and its conversation as a Markdown issue draft for handoff to another tracker.

Two MCP prompts are available: analyze-ticket asks the model to summarize a ticket and its timeline, while draft-ticket-response prepares a customer-facing reply and includes a confirmation step before posting. An optional Help Center resource can expose knowledge base articles. With Git-Zen configured, the server can retrieve linked GitLab issues, merge requests, and commits.

How it works

The server uses a Zendesk OAuth client. During setup, it asks for the Zendesk subdomain, OAuth client ID, and client secret, then opens an authorization flow in a browser. If a browser is unavailable, it prints the authorization URL and accepts the resulting redirect URL in the terminal.

Credentials and token metadata are written to ~/.config/zendesk-mcp/config.json with restrictive file permissions. The setup requests an access token and refresh token, and the server refreshes the access token as needed. If authorization expires or is revoked, the tools report that setup must be run again.

The server runs from a project-local Python virtual environment and is registered with an MCP client as a command using that environment's Python executable. Claude Code's example registration uses the server's absolute path because its launch shell does not inherit an activated virtual environment.

Setup and configuration

Python 3.10 or newer is required. From a repository checkout, create a virtual environment and install the package in editable mode:

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

Run the interactive configuration with:

.venv/bin/python -m zendesk_mcp setup

The Zendesk OAuth client needs read write scopes and a redirect URL of http://localhost:8787/callback. An administrator creates the OAuth client in Zendesk. Git-Zen field configuration and Help Center access are optional choices during setup.

Tools and capabilities

• Search tickets by status, priority, type, assignee, requester, tags, or keyword.
• List, inspect, update, create, assign, and change the status of tickets.
• Read conversations and attachments, or download an attachment to a local cache.
• Post public replies and internal agent notes.
• Browse active views and macros, preview macro changes, and apply macros.
• Find users, inspect groups and their members, retrieve organizations, and list custom statuses.
• Read and log ticket time entries.
• Produce Markdown ticket context and, when Git-Zen is enabled, retrieve linked GitLab records.

Write tools are not included in the example Claude Code default allow-list, so Claude prompts for approval before those operations. The read tools shown in the example can be allowed in ~/.claude/settings.json.

Limitations and notes

The server requires a Zendesk OAuth client and an authorized Zendesk account; setup is not based on a simple environment-variable configuration. Access tokens and refresh tokens are stored locally, so the configuration file must remain protected.

GitLab link retrieval depends on the optional Git-Zen integration and its configured Zendesk field. Help Center access is also optional. The repository documentation explicitly demonstrates registration with Claude Code and describes support for other MCP clients, but does not provide client-specific setup instructions for each client.