zendesk-mcp
Provides tools for interacting with Zendesk Support and Help Center APIs, enabling ticket search, retrieval, creation, updating, commenting, user and organization management, and knowledge base article search.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@zendesk-mcp show me my open high priority tickets"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
zendesk-mcp
A self-hosted MCP server that connects AI assistants (Claude Code, Codex, Cursor) to your Zendesk account. 14 curated tools over the official Zendesk Support and Help Center APIs. No third-party services in between: your API token talks directly to Zendesk from your machine.
How it works: server and client are two different things
There are two pieces, with different requirements:
The server is this project: a small Python process that holds your Zendesk credentials and makes the API calls. It needs Python, uv and a Zendesk API token.
The client is your AI assistant (Claude Code, Codex or Cursor). It needs no Python and never sees your Zendesk token directly; it just calls the server's tools.
In the default local setup, your machine plays both roles at once: the client starts the server automatically in the background each session (you never run the server manually) and talks to it over stdio. Nothing is exposed to the network.
[ your machine ] [ internet ]
Client (Claude Code / Codex / Cursor)
└─ starts → Server (this repo, Python) ──→ Zendesk API
holds ZENDESK_API_TOKENLater, the server can move to its own machine (a VPS) and serve several people; the requirements split accordingly. See "Remote deployment" below.
Related MCP server: zendesk-mcp-server
Tools
Tool | Type | What it does |
| read | Search tickets with Zendesk query syntax |
| read | Full detail of one ticket |
| read | Conversation thread (replies + internal notes) |
| read | User by ID |
| read | Find users by name or email |
| read | Find organizations by name |
| read | All tickets of one organization |
| read | Search Help Center knowledge base |
| read | Full article body |
| write | Create a ticket (auto-creates requester if new) |
| write | Change status, priority, assignee, tags |
| write | Internal note (default) or public reply |
| write | Idempotent upsert by email or external_id |
| write | Idempotent upsert by external_id |
Server setup (your machine)
These requirements are for the server role of your machine.
Python 3.10+ and uv (a fast Python package manager):
# Windows powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"# macOS / Linux curl -LsSf https://astral.sh/uv/install.sh | shA Zendesk API token: in Zendesk, go to Admin Center > Apps and integrations > APIs > Zendesk API > Add API token. Copy it immediately (it is shown only once). Make sure "Token access" is enabled on that page. Reference:
https://support.zendesk.com/hc/en-us/articles/4408889192858The token inherits ALL permissions of the user who created it. Prefer creating it from a user with agent (not admin) role if you can.
Then install:
git clone https://github.com/miguel-escribano/zendesk-mcp.git
cd zendesk-mcp
uv syncThat is all for the server. You never start it manually in local use: the client does it for you.
Client setup (connect your assistant)
These steps are for the client role: telling your AI assistant where the server lives and which credentials to hand it at startup. The client itself needs no Python.
You need three values: your subdomain (yourcompany if your Zendesk is yourcompany.zendesk.com), the email of the Zendesk user that owns the token, and the token itself.
Claude Code
claude mcp add zendesk \
-e ZENDESK_SUBDOMAIN=yourcompany \
-e ZENDESK_EMAIL=you@yourcompany.com \
-e ZENDESK_API_TOKEN=your-token \
-- uv run --directory /absolute/path/to/zendesk-mcp zendesk-mcpCodex
Add to ~/.codex/config.toml:
[mcp_servers.zendesk]
command = "uv"
args = ["run", "--directory", "/absolute/path/to/zendesk-mcp", "zendesk-mcp"]
[mcp_servers.zendesk.env]
ZENDESK_SUBDOMAIN = "yourcompany"
ZENDESK_EMAIL = "you@yourcompany.com"
ZENDESK_API_TOKEN = "your-token"Cursor
Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):
{
"mcpServers": {
"zendesk": {
"command": "uv",
"args": ["run", "--directory", "/absolute/path/to/zendesk-mcp", "zendesk-mcp"],
"env": {
"ZENDESK_SUBDOMAIN": "yourcompany",
"ZENDESK_EMAIL": "you@yourcompany.com",
"ZENDESK_API_TOKEN": "your-token"
}
}
}
}On Windows, use a full path like C:/projects/zendesk-mcp in the --directory argument.
Test it: restart your client and ask: "search my open Zendesk tickets". You should see results from your account.
Supervised use
This server exposes write tools (create_ticket, update_ticket, add_ticket_comment, upserts) with no restrictions of its own. It is designed for supervised, human-in-the-loop use: your MCP client asks for approval before each write call (Claude Code does this by default). Do not wire it into unattended/autonomous agents without adding your own safeguards. add_ticket_comment defaults to internal notes; customer-visible replies require public=true explicitly.
Privacy note
Every tool call puts ticket content, including end-customer names, emails and message bodies, into the context of the LLM you are using. Review your privacy obligations (e.g. GDPR, customer DPAs) before using this with real customer data.
Multiple Zendesk accounts
The server handles one Zendesk instance per process by design. For several accounts, register the server multiple times in your client with different names and env vars, e.g. zendesk-acme and zendesk-globex, each with its own ZENDESK_SUBDOMAIN / ZENDESK_EMAIL / ZENDESK_API_TOKEN.
Remote deployment (optional)
This is where the two roles physically split: the server (Python, uv, Zendesk token) moves to a VPS, and each teammate's machine keeps only the client role, with zero local installs. The same code runs as a shared HTTP server:
export ZENDESK_SUBDOMAIN=... ZENDESK_EMAIL=... ZENDESK_API_TOKEN=...
export MCP_TRANSPORT=http MCP_HTTP_PORT=8000
export MCP_AUTH_TOKEN=$(openssl rand -hex 32) # clients must send this as a Bearer token
uv run zendesk-mcpThe server binds to 127.0.0.1 and refuses to start without MCP_AUTH_TOKEN. Put a reverse proxy with TLS in front (Caddy, nginx) and be aware that your Zendesk token now lives on that server: use a dedicated Zendesk user, restrict access, rotate the token periodically. Clients connect with:
claude mcp add --transport http zendesk https://your-host/mcp --header "Authorization: Bearer <MCP_AUTH_TOKEN>"For multi-user OAuth instead of a shared bearer token, see FastMCP auth providers (https://gofastmcp.com); not needed for a small trusted team.
Troubleshooting
401 Unauthorized: wrong email or token, or token access disabled in Admin Center > Apps and integrations > APIs.
403 Forbidden: the Zendesk user owning the token lacks permission for that action.
Server not found / spawn error: check the
--directorypath is absolute anduvis on your PATH (restart the terminal after installing uv).Inspect tools manually:
npx @modelcontextprotocol/inspector uv run --directory /path/to/zendesk-mcp zendesk-mcp
Alternatives
If you prefer not to self-host, Swifteq offers a managed Zendesk MCP/AI integration (https://swifteq.com/zendesk-chatgpt-app and their free MCP Server app on the Zendesk Marketplace). Trade-off: zero maintenance, but a third party sits between your AI client and your Zendesk data.
License
MIT
Available Tools
14 toolsadd_ticket_commentA
WRITE: Add a comment to a ticket (PUT /api/v2/tickets/{id} with a comment object). Defaults to an internal note; set public=true only to send a customer-visible reply.
Inputs: body (required), ticket_id (required), public. Returns: object
create_or_update_organizationA
WRITE: Create an organization, or update it if one matches by external_id (POST /api/v2/organizations/create_or_update). Idempotent.
Inputs: name (required), tags, notes, external_id, +1 more. Returns: object
create_or_update_userA
WRITE: Create a user, or update it if one already exists with the same email or external_id (POST /api/v2/users/create_or_update). Idempotent: cannot create duplicates.
Inputs: name (required), email (required), role, phone, +2 more. Returns: object
create_ticketC
WRITE: Create a new ticket (POST /api/v2/tickets).
Inputs: subject (required), comment_body (required), tags, type, +3 more. Returns: object
get_articleA
Get one Help Center article including its full HTML body (GET /api/v2/help_center/articles/{id}).
Inputs: article_id (required). Returns: object
get_ticketA
Get full details of one ticket (GET /api/v2/tickets/{id}).
Inputs: ticket_id (required). Returns: object
get_ticket_commentsA
Get the conversation thread of a ticket, public replies and internal notes, newest first (GET /api/v2/tickets/{id}/comments).
Inputs: ticket_id (required), per_page. Returns: Generic wrapper for non-object return types.
get_userA
Get a Zendesk user by ID (GET /api/v2/users/{id}). Use to resolve requester_id / assignee_id values returned by ticket tools.
Inputs: user_id (required). Returns: object
list_org_ticketsA
List all tickets of one organization, the account-health view (GET /api/v2/organizations/{id}/tickets). Use search_organizations first to get the organization_id.
Inputs: organization_id (required), page, per_page. Returns: object
search_articlesA
Search Help Center knowledge base articles by relevance (GET /api/v2/help_center/articles/search). Use before answering questions that the knowledge base may already cover.
Inputs: query (required), locale, per_page. Returns: object
search_organizationsA
Find organizations by name (GET /api/v2/organizations/autocomplete). Returns organizations whose names begin with the given value.
Inputs: name (required). Returns: Generic wrapper for non-object return types.
search_ticketsA
Search tickets (GET /api/v2/search). Use this first to find tickets, then get_ticket / get_ticket_comments for detail. Returns slim tickets. API caps results at 1000 per query; narrow with date ranges if needed.
Inputs: query (required), page, sort_by, per_page. Returns: object
search_usersA
Search users by name or email (GET /api/v2/users/search).
Inputs: query (required). Returns: Generic wrapper for non-object return types.
update_ticketA
WRITE: Update ticket fields: status, priority, assignee, tags (PUT /api/v2/tickets/{id}). Does not add comments; use add_ticket_comment for that.
Inputs: ticket_id (required), tags, status, priority, +1 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Each tool targets a distinct resource-action pair: ticket creation/update/comment/search/get/comments, user search/get/upsert, org search/upsert/ticket-listing, and article search/get. No overlapping purposes; even search_tickets vs list_org_tickets have clearly different scopes.
All tool names follow a consistent verb_noun pattern in snake_case (create_ticket, search_users, get_article, list_org_tickets, etc.). The verb prefixes are uniform (create, update, add, get, search, list), with only minor abbreviation like 'org' that doesn't break the pattern.
14 tools is well-scoped for a Zendesk server, covering four core entities (tickets, users, organizations, articles) with essential operations. Each tool earns its place without redundancy or bloat.
The surface covers the main workflows: full ticket lifecycle (create, update, comment, search, get, comments), user lookup/upsert, organization search/upsert and ticket listing, plus article search/get. Minor gaps like delete operations or get_organization by ID exist, but agents can work around them with current tools.
Related MCP Connectors
Connect Claude, ChatGPT or any AI assistant to Zendesk tickets, CSAT, macros and Help Center.
Zendesk configuration management for AI agents: propose, review, apply and roll back changes.
Zendesk MCP server for ChatGPT, Claude and any AI agent: list tickets, reply to ticket, update ticket, apply macro, add internal note and search tickets in your own Zendesk account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Zendesk yourself; Cotlet does not store your password and you need no Zendesk API key. About the official Zendesk API: Zendesk has a full REST API, the Support API (also called the Ticketing API), but no documented Zendesk-hosted MCP server for working tickets (checked 16 Oct 2026). Zendesk's MCP documentation covers the MCP client, where Zendesk calls other servers. Setup and FAQ: https://cotlet.dev/integrations/zendesk-api-mcp-server
Work your Zono Support help desk from an AI client: tickets, customers, purchases and knowledge.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to search tickets, manage tags, create tickets, inspect automations, and more in Zendesk.MIT
- AlicenseAqualityDmaintenanceConnects AI assistants to Zendesk, enabling natural language queries over support tickets, help articles, and customer feedback.6MIT
- AlicenseNot gradedqualityDmaintenanceModel Context Protocol (MCP) server for Zendesk Support that connects AI agents to 14 ticket tools including create, search, assign, close, comments, and metrics.Apache 2.0
- FlicenseNot gradedqualityAmaintenanceEnables integration with Zendesk to retrieve and manage tickets and comments, analyze tickets, draft responses, and access Help Center articles as a knowledge base.-