Skip to content
Back to search

zendesk-mcp-server

A Model Context Protocol server for Zendesk

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/reminia--zendesk-mcp-server/badge.svg)](/listings/reminia--zendesk-mcp-server)

HTML

<a href="/listings/reminia--zendesk-mcp-server"><img src="/api/listings/reminia--zendesk-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

- build: `uv venv && uv pip install -e .` or `uv build` in short. - configure authentication: see [Authentication](#authentication) below. - configure in Claude desktop:

{
  "mcpServers": {
      "zendesk": {
          "command": "uv",
          "args": [
              "--directory",
              "/path/to/zendesk-mcp-server",
              "run",
              "zendesk"
          ]
      }
  }
}

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 330 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Zendesk MCP Server
  2. ![ci](https://github.com/reminia/zendesk-mcp-server/actions/workflows/ci.yml/badge.svg)
  3. [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
  4. A Model Context Protocol server for Zendesk.
  5. This server provides a comprehensive integration with Zendesk. It offers:
  6. - Tools for retrieving and managing Zendesk tickets and comments
  7. - Specialized prompts for ticket analysis and response drafting
  8. - Full access to the Zendesk Help Center articles as knowledge base
  9. ![demo](https://res.cloudinary.com/leecy-me/image/upload/v1736410626/open/zendesk_yunczu.gif)
  10. ## Setup
  11. - build: `uv venv && uv pip install -e .` or `uv build` in short.
  12. - configure authentication: see [Authentication](#authentication) below.
  13. - configure in Claude desktop:
  14. ```json
  15. {
  16. "mcpServers": {
  17. "zendesk": {
  18. "command": "uv",
  19. "args": [
  20. "--directory",
  21. "/path/to/zendesk-mcp-server",
  22. "run",
  23. "zendesk"
  24. ]
  25. }
  26. }
  27. }
  28. ```
  29. ## Authentication
  30. This server authenticates with OAuth. Each operator authorizes with their own
  31. Zendesk login, so API calls carry their identity and Zendesk applies exactly the
  32. permissions it applies in the UI — their role, their group restrictions, their
  33. ticket access. Comments they post are authored by them.
  34. API token authentication still works but is deprecated. See
  35. [Migrating from an API token](#migrating-from-an-api-token).
  36. ### 1. Register a public OAuth client
  37. In Admin Center, go to **Apps and integrations > APIs > OAuth clients** and
  38. create a client:
  39. | Field | Value |
  40. | --- | --- |
  41. | Client kind | **Public** — this server runs on each operator's machine, so there is no secret it could keep. PKCE is used instead. |
  42. | Redirect URLs | `http://localhost:4567/callback` |
  43. | Allowed scopes | `tickets:read tickets:write ticket_attachments:read users:read hc:read` |
  44. Setting **Allowed scopes** is optional but recommended: it caps what any token
  45. from this client can ever request, even if the code changes.
  46. Note the client's **Identifier** — that is the `ZENDESK_CLIENT_ID` below.
  47. If Zendesk rejects `http://localhost:4567/callback`, register `https://localhost`
  48. instead and use `zendesk-auth --manual` in step 3.
  49. ### 2. Configure the environment
  50. Copy `.env.example` to `.env` and set:
  51. ```bash
  52. ZENDESK_SUBDOMAIN=acme # for https://acme.zendesk.com
  53. ZENDESK_CLIENT_ID=your-client-identifier
  54. ```
  55. Keep `.env` out of version control.
  56. Two optional settings, both of which must agree with the OAuth client:
  57. | Variable | Default | When to change it |
  58. | --- | --- | --- |
  59. | `ZENDESK_OAUTH_REDIRECT_URI` | `http://localhost:4567/callback` | Port 4567 is in use, or the client is registered with a different redirect URL. Must match a redirect URL on the client exactly. |
  60. | `ZENDESK_TOKEN_FILE` | `$XDG_CONFIG_HOME/zendesk-mcp/tokens.json` | Storing tokens elsewhere, for example a Docker volume. |
  61. ### 3. Authorize this machine, once
  62. ```bash
  63. uv run zendesk-auth
  64. ```
  65. This opens a browser, asks the operator to approve access, and stores the
  66. resulting tokens locally. From then on the server renews access on its own; the
  67. operator never repeats this unless the tokens are revoked or left unused past the
  68. refresh token's lifetime (90 days as requested by this server).
  69. If the browser cannot reach this machine — a remote shell, or an OAuth client
  70. registered with `https://localhost` — use the paste-based flow instead:
  71. ```bash
  72. uv run zendesk-auth --manual
  73. ```
  74. Tokens are written to `$XDG_CONFIG_HOME/zendesk-mcp/tokens.json`
  75. (`~/.config/zendesk-mcp/tokens.json` by default), created `0600` inside a `0700`
  76. directory. Override the location with `ZENDESK_TOKEN_FILE`. The file holds live
  77. credentials: treat it like a password and never commit it.
  78. ### How token renewal works
  79. Zendesk access tokens are short-lived — 30 minutes by default, 48 hours at most —
  80. so the server refreshes them for you:
  81. - **before expiry**, when the stored token is within 60 seconds of expiring, and
  82. - **on rejection**, when Zendesk answers `401` with `{"error": "invalid_token"}`,
  83. in which case the request is retried once with a fresh token.
  84. Only `invalid_token` triggers a retry. A `401` or `403` from insufficient scope or
  85. from the operator's own Zendesk permissions is passed through unchanged, so
  86. permission problems stay visible instead of looking like auth flakiness.
  87. Each refresh rotates the refresh token and invalidates the previous one
  88. immediately, so the new pair is written to disk before it is used. Writes are
  89. atomic and guarded by a lock file, which matters if you run the server from more
  90. than one MCP client at the same time.
  91. When the refresh token itself is expired or revoked, tools fail with a message
  92. telling the operator to re-run `zendesk-auth`.
  93. ### Choosing scopes
  94. The default scopes cover every tool this server exposes:
  95. | Scope | Needed for |
  96. | --- | --- |
  97. | `tickets:read` | `get_ticket`, `get_tickets`, `get_ticket_comments` |
  98. | `tickets:write` | `create_ticket`, `update_ticket`, `create_ticket_comment` |
  99. | `ticket_attachments:read` | `get_ticket_attachment` |
  100. | `users:read` | requester and assignee details on tickets |
  101. | `hc:read` | the `zendesk://knowledge-base` resource |
  102. Narrow them with `ZENDESK_OAUTH_SCOPES` if you do not need every tool — for
  103. read-only access, `tickets:read users:read hc:read`.
  104. Scopes are a ceiling, not a grant: a token can never do more than the
  105. authorizing operator is allowed to do. Note that Zendesk accepts unrecognised
  106. scope names when issuing a token but then rejects every request with `403`, so
  107. `zendesk-auth` prints the scope Zendesk actually granted for comparison.
  108. ### Migrating from an API token
  109. Zendesk is retiring API tokens on this schedule:
  110. | Date | Change |
  111. | --- | --- |
  112. | 2026-07-28 | Tokens unused for 30 days are deactivated automatically; new accounts cannot create tokens. |
  113. | 2026-10-27 | No account can create new API tokens. |
  114. | 2027-04-30 | All API tokens stop working permanently. |
  115. Until then `ZENDESK_EMAIL` + `ZENDESK_API_KEY` continue to work, and the server
  116. logs a deprecation warning the first time it authenticates. Set
  117. `ZENDESK_CLIENT_ID` and OAuth takes precedence, so you can migrate without
  118. removing the old variables.
  119. Beyond the deadline, there is a reason to move sooner: a Zendesk API token is
  120. account-level and unscoped. Whoever holds it gets the full access of the user it
  121. is paired with, which for most installations is an admin. That is what per-operator
  122. OAuth fixes.
  123. > **Why not the client credentials flow?** It is simpler — no browser step, no
  124. > refresh tokens — but its tokens are attributed to the Zendesk user who created
  125. > the OAuth client. Every operator would act as that one user, usually an admin,
  126. > and audit logs and comment authorship would all point at them. Since the goal
  127. > is for operators to have exactly their own Zendesk permissions, the
  128. > authorization code flow is the only one that fits.
  129. ## Docker
  130. You can containerize the server if you prefer an isolated runtime:
  131. 1. Copy `.env.example` to `.env` and fill in your Zendesk configuration. Keep this file outside version control.
  132. 2. Build the image:
  133. ```bash
  134. docker build -t zendesk-mcp-server .
  135. ```
  136. 3. Authorize on the **host**, not in the container. `zendesk-auth` needs a
  137. browser and a local callback port, so run it once outside Docker:
  138. ```bash
  139. uv run zendesk-auth
  140. ```
  141. 4. Run the server, passing the environment file and mounting the token store:
  142. ```bash
  143. docker run --rm \
  144. --env-file /path/to/.env \
  145. --user "$(id -u):$(id -g)" \
  146. -e ZENDESK_TOKEN_FILE=/tokens/tokens.json \
  147. -v "$HOME/.config/zendesk-mcp:/tokens" \
  148. zendesk-mcp-server
  149. ```
  150. The mount must be writable: the server rewrites the file every time it
  151. rotates the refresh token, and a read-only mount will strand it on an expired
  152. token. `--user` makes the container run as you, so it can read the `0600`
  153. token file created on the host.
  154. Add `-i` when wiring the container to MCP clients over STDIN/STDOUT (Claude Code uses this mode). For daemonized runs, add `-d --name zendesk-mcp`.
  155. The image installs dependencies from `requirements.lock` and drops privileges to a non-root user. With API token authentication no volume is needed, since configuration comes entirely from environment variables.
  156. ### Claude MCP Integration
  157. To use the Dockerized server from Claude Code/Desktop, add an entry to Claude Code's `settings.json` similar to:
  158. ```json
  159. {
  160. "mcpServers": {
  161. "zendesk": {
  162. "command": "/usr/local/bin/docker",
  163. "args": [
  164. "run",
  165. "--rm",
  166. "-i",
  167. "--env-file",
  168. "/path/to/zendesk-mcp-server/.env",
  169. "zendesk-mcp-server"
  170. ]
  171. }
  172. }
  173. }
  174. ```
  175. Adjust the paths to match your environment. After saving the file, restart Claude for the new MCP server to be detected.
  176. ## Development
  177. Run the test suite:
  178. ```bash
  179. uv pip install -e '.[test]'
  180. pytest
  181. ```
  182. The tests use mocked HTTP and never contact Zendesk. They cover the API-token and
  183. OAuth paths, PKCE derivation, token storage and rotation, and each of the four
  184. ways this server calls Zendesk.
  185. ## Resources
  186. - zendesk://knowledge-base, get access to the whole help center articles.
  187. ## Prompts
  188. ### analyze-ticket
  189. Analyze a Zendesk ticket and provide a detailed analysis of the ticket.
  190. ### draft-ticket-response
  191. Draft a response to a Zendesk ticket.
  192. ## Tools
  193. ### get_tickets
  194. Fetch the latest tickets with pagination support
  195. - Input:
  196. - `page` (integer, optional): Page number (defaults to 1)
  197. - `per_page` (integer, optional): Number of tickets per page, max 100 (defaults to 25)
  198. - `sort_by` (string, optional): Field to sort by - created_at, updated_at, priority, or status (defaults to created_at)
  199. - `sort_order` (string, optional): Sort order - asc or desc (defaults to desc)
  200. - Output: Returns a list of tickets with essential fields including id, subject, status, priority, description, timestamps, and assignee information, along with pagination metadata
  201. ### get_ticket
  202. Retrieve a Zendesk ticket by its ID
  203. - Input:
  204. - `ticket_id` (integer): The ID of the ticket to retrieve
  205. ### get_ticket_comments
  206. Retrieve all comments for a Zendesk ticket by its ID
  207. - Input:
  208. - `ticket_id` (integer): The ID of the ticket to get comments for
  209. ### create_ticket_comment
  210. Create a new comment on an existing Zendesk ticket
  211. - Input:
  212. - `ticket_id` (integer): The ID of the ticket to comment on
  213. - `comment` (string): The comment text/content to add
  214. - `public` (boolean, optional): Whether the comment should be public (defaults to true)
  215. ### create_ticket
  216. Create a new Zendesk ticket
  217. - Input:
  218. - `subject` (string): Ticket subject
  219. - `description` (string): Ticket description
  220. - `requester_id` (integer, optional)
  221. - `assignee_id` (integer, optional)
  222. - `priority` (string, optional): one of `low`, `normal`, `high`, `urgent`
  223. - `type` (string, optional): one of `problem`, `incident`, `question`, `task`
  224. - `tags` (array[string], optional)
  225. - `custom_fields` (array[object], optional)
  226. ### update_ticket
  227. Update fields on an existing Zendesk ticket (e.g., status, priority, assignee)
  228. - Input:
  229. - `ticket_id` (integer): The ID of the ticket to update
  230. - `subject` (string, optional)
  231. - `status` (string, optional): one of `new`, `open`, `pending`, `on-hold`, `solved`, `closed`
  232. - `priority` (string, optional): one of `low`, `normal`, `high`, `urgent`
  233. - `type` (string, optional)
  234. - `assignee_id` (integer, optional)
  235. - `requester_id` (integer, optional)
  236. - `tags` (array[string], optional)
  237. - `custom_fields` (array[object], optional)
  238. - `due_at` (string, optional): ISO8601 datetime

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.