# michaelrice/zendesk-mcp [Health: Active]

**Category:** 🎧 Support & Service Management  
**Repository:** https://github.com/michaelrice/zendesk-mcp  
**GitHub Stars:** 8  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/michaelrice-zendesk-mcp

## Description
MCP server for Zendesk. Read/write tools for tickets, comments, views, macros, users, groups, organizations, and time tracking; optional Help Center knowledge base and Git-Zen GitLab integration.

## Tools
Capabilities this server exposes over MCP:

- **zendesk_get_ticket** — Get a Zendesk ticket by ID. Returns ticket fields including status, priority, requester, assignee, tags, and description.
- **zendesk_search_tickets** — Search Zendesk tickets by keyword and/or status. keywords: free-text search (e.g. 'login failure LDAP'). status: new, open, pending, hold, solved, closed — leave empty for all statuses. Returns id, subject, status, requester, assignee, and dates.
- **zendesk_get_comments** — Get all comments (public replies and internal notes) for a Zendesk ticket. Includes attachment metadata but does not download files.
- **zendesk_list_attachments** — List all attachments across all comments for a Zendesk ticket. Returns filename, content type, size, and download URL for each. Use zendesk_download_attachment to fetch file contents.
- **zendesk_download_attachment** — Download a Zendesk attachment. Obtain attachment_url and filename from zendesk_list_attachments. ticket_id is required for cache organization. Optional dest_dir overrides the default cache location (it must be inside the cache or a directory listed in 'attachment_allowed_dest_dirs' in the config); the file is written there and (for archives) extracted alongside it. Archives return a file list and unpack_dir — read individual files with your normal file tools. PDFs return up to ~500KB of extracted text. Images are base64-encoded.
- **zendesk_ticket_to_gitlab_context** — Format a Zendesk ticket and its comments as an issue draft. Returns Markdown with ticket metadata, full conversation, and an empty Steps to Reproduce section. Use this output as the description when creating an issue in your tracker.
- **zendesk_post_comment** — Post a public reply on a Zendesk ticket. The reply is visible to the requester. Use for customer-facing responses.
- **zendesk_post_internal_note** — Post an internal note on a Zendesk ticket. Internal notes are only visible to agents and are not sent to the requester.
- **zendesk_set_ticket_status** — Set the status of a Zendesk ticket. Valid statuses: new, open, pending, hold, solved, closed.
- **zendesk_assign_ticket** — Assign a Zendesk ticket to an agent by their email address. Pass 'me' as assignee_email to assign the ticket to yourself (the authenticated user).
- **zendesk_update_ticket** — Update one or more fields on a Zendesk ticket. Pass only the fields you want to change. status: new/open/pending/hold/solved/closed. priority: low/normal/high/urgent. type: problem/incident/question/task. assignee_id, requester_id, group_id, custom_status_id are integer IDs. due_at is ISO8601. Returns JSON of the refreshed ticket.
- **zendesk_get_time_tracking** — Get time tracking data for a Zendesk ticket. Returns total time spent and time spent on the last update, in both seconds and human-readable format (e.g. '2h 15m').
- **zendesk_log_time** — Log time spent on a Zendesk ticket. Adds seconds to the running total and records it as the last-update time. Returns logged amount and new total in seconds and human-readable format.
- **zendesk_get_git_zen_links** — Get linked GitLab issues, merge requests, and commits for a Zendesk ticket via the Git-Zen integration. Returns structured lists with state, labels, weight, and direct GitLab links.
- **zendesk_create_ticket** — Create a new Zendesk ticket. subject and description are required. priority: low/normal/high/urgent. type: problem/incident/question/task. requester_id/assignee_id are user IDs (integers). custom_fields is a list of {id, value} dicts. Returns JSON of the created ticket.
- **zendesk_get_tickets** — List Zendesk tickets with pagination. page: 1-based page number. per_page: max 100. sort_by: created_at, updated_at, priority, or status. sort_order: asc or desc. Returns tickets plus pagination metadata.
- **zendesk_add_tag** — Add a tag to a Zendesk ticket. Idempotent: adding an existing tag returns the current tag list without modifying the ticket. Returns JSON with ticket_id and current tags.
- **zendesk_remove_tag** — Remove a tag from a Zendesk ticket. Idempotent: removing a tag that isn't present returns the current tag list without modifying the ticket. Returns JSON with ticket_id and current tags.
- **zendesk_list_views** — List all active Zendesk views. Returns JSON array of {id, title}.
- **zendesk_get_view** — Get a Zendesk view's definition including filter conditions and execution settings. Returns JSON with id, title, active, conditions, execution.
- **zendesk_get_view_tickets** — Get the tickets currently matching a Zendesk view. Returns JSON array of tickets with essential fields.
- **zendesk_list_macros** — List all active Zendesk macros with their actions. Returns JSON array of {id, title, description, actions: [{field, value}]}.
- **zendesk_preview_macro** — Preview the effect a macro would have (without applying it). Returns the result payload from Zendesk's apply preview endpoint.
- **zendesk_apply_macro** — Apply a macro to a Zendesk ticket. Fetches the macro preview, applies field changes, and posts any comment included in the macro. Returns JSON with id, status, tags, applied_changes, comment_added.
- **zendesk_search_users** — Search Zendesk users by name or email. Returns JSON array of {id, name, email, role}.
- **zendesk_get_groups** — List all active Zendesk groups (excluding deleted). Returns JSON array of {id, name}.
- **zendesk_get_group_users** — List the members of a Zendesk group. Returns JSON array of {id, name, email}.
- **zendesk_get_organization** — Fetch a Zendesk organization including its custom fields and tags. Returns JSON with id, name, organization_fields, tags, created_at, updated_at.
- **zendesk_list_custom_statuses** — List all custom ticket statuses defined in Zendesk. Returns JSON array of {id, agent_label, end_user_label, status_category, active, default}. Use the id when setting custom_status_id on a ticket.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "zendesk-mcp": {
    "command": "uvx",
    "args": ["zendesk-mcp"]
  }
}
```

## Documentation

## 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:

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

Run the interactive configuration with:

```bash
.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.

_Full upstream README: https://allmcps.com/mcp/michaelrice-zendesk-mcp/readme_