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.
LABSCO SUMMARY
Reads and writes deliberately kept apart.
Replying to the customer and noting something for colleagues are two different tools rather than one tool with a flag, which is the distinction an agent is most likely to get wrong. The handoff tool is the other thing worth noticing: it turns a ticket and its whole conversation into a Markdown issue draft with an empty reproduction section — exactly the shape a bug tracker wants, and the step that usually gets done badly by hand.
What it is
A Zendesk server covering an agent's day: tickets searched, listed and read with their conversation and attachments; public replies and internal notes posted; status, assignee, tags and fields updated; views and macros browsed and applied; users, groups and organisations looked up; and time logged. Two prompts ship with it, surfacing as slash commands in clients that support them.
What you get
- zendesk_search_tickets by keyword and status, zendesk_get_tickets with pagination and sorting, and zendesk_get_ticket for one ticket's fields.
- zendesk_get_comments returns the whole thread — public replies and internal notes together — with attachment metadata, and zendesk_list_attachments and zendesk_download_attachment pull the files into a local cache directory.
- zendesk_create_ticket and zendesk_update_ticket, the latter touching only the fields you pass, including group, custom status, tags and custom fields.
- Replying is deliberately two tools: zendesk_post_comment is customer-facing, zendesk_post_internal_note is agent-only.
- zendesk_set_ticket_status, zendesk_assign_ticket by an agent's email or 'me', and zendesk_add_tag and zendesk_remove_tag, both idempotent.
- Views and macros: zendesk_list_views, zendesk_get_view for its conditions, zendesk_get_view_tickets for what currently matches, and zendesk_list_macros, zendesk_preview_macro and zendesk_apply_macro.
- Directory lookups: zendesk_search_users, zendesk_get_groups, zendesk_get_group_users, zendesk_get_organization with its custom fields, and zendesk_list_custom_statuses for the IDs an update needs.
- zendesk_get_time_tracking and zendesk_log_time read and add against a ticket's running total.
- zendesk_ticket_to_gitlab_context turns a ticket and its whole conversation into a Markdown issue draft with an empty reproduction section, and zendesk_get_git_zen_links reads linked GitLab issues, merge requests and commits when the Git-Zen app is installed.
- Optionally, Help Center articles exposed as an MCP resource.
Requirements
Python 3.10 or newer, installed into a virtual environment. A Zendesk OAuth client that an admin creates on your instance with read and write scopes and a localhost callback URL; an interactive setup opens the browser once and stores the token locally. The Git-Zen tool needs that Zendesk app installed, and does nothing without it.
Setup effort
One command, then sign in — uvx zendesk-mcp, then approve the OAuth sign-in
USE CASES
01
Working out what a ticket is really about
Read the ticket, then the whole thread including the internal notes, before deciding anything.
02
Finding the tickets that match a pattern
Search by keyword and status, or open a saved view and take what currently matches it.
03
Drafting and posting a reply
Write the customer-facing response with the right tool, and leave the working notes on the agent-only one.
04
Moving a ticket along
Set the status, assign it to the right agent by email, and tag it — tagging twice changes nothing.
05
Applying a canned response without surprises
List the macros, preview exactly what one would change, then apply it.
06
Turning a support ticket into an engineering issue
Format the ticket and its conversation as a Markdown issue draft, and check what is already linked to it.
07
Logging the time you spent
Read the running total on the ticket and add what this session took.
29 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
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_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_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_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; 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_get_comments
Get all comments (public replies and internal notes) for a Zendesk ticket. Includes attachment metadata but does not download files.
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_get_group_users
List the members of a Zendesk group. Returns JSON array of {id, name, email}.
zendesk_get_groups
List all active Zendesk groups (excluding deleted). Returns JSON array of {id, name}.
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_get_ticket
Get a Zendesk ticket by ID. Returns ticket fields including status, priority, requester, assignee, tags, and description.
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_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_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_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_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.
zendesk_list_macros
List all active Zendesk macros with their actions. Returns JSON array of {id, title, description, actions: [{field, value}]}.
zendesk_list_views
List all active Zendesk views. Returns JSON array of {id, title}.
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_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_preview_macro
Preview the effect a macro would have (without applying it). Returns the result payload from Zendesk's apply preview endpoint.
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_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_search_users
Search Zendesk users by name or email. Returns JSON array of {id, name, email, role}.
zendesk_set_ticket_status
Set the status of a Zendesk ticket. Valid statuses: new, open, pending, hold, solved, closed.
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_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.
BEFORE YOU INSTALL
What to know first
Tools you get
29 tools when we connected. zendesk_get_git_zen_links returns a 'not configured' message until you set git_zen_field_id.
Requires
- Python 3.10 or newer
- A Zendesk OAuth client created by a Zendesk admin, with redirect URL http://localhost:8787/callback and scopes read write
CONTEXT COST
Light Standing cost
Rated by the size of the 29 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
Setup
Clone the repository and install it into a virtualenv
TERMINAL
git clone https://github.com/michaelrice/zendesk-mcp.git
cd zendesk-mcp
python3 -m venv .venv
.venv/bin/pip install --upgrade pip
.venv/bin/pip install -e .Run the interactive setup using the venv's Python
TERMINAL
.venv/bin/python -m zendesk_mcp setupuvx
TERMINAL
uvx zendesk-mcpMCP Clients
Claude Code
From the repository root, after install, register the server with the venv's Python by absolute path:
CLAUDE CODE · TERMINAL
ZENDESK_MCP_DIR="$(pwd)"
claude mcp add --scope user zendesk -- "$ZENDESK_MCP_DIR/.venv/bin/python" -m zendesk_mcpOptionally, add the read tools to permissions.allow in ~/.claude/settings.json to avoid per-call prompts:
CLAUDE CODE · 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"
]
}
}
