Server data from the Official MCP Registry
Zendesk Support & Help Center MCP server with per-user OAuth 2.1 PKCE authentication.
Zendesk Support & Help Center MCP server with per-user OAuth 2.1 PKCE authentication.
Valid MCP server (2 strong, 1 medium validity signals). No known CVEs in dependencies. Package registry verified. Imported from the Official MCP Registry.
5 files analyzed · 1 issue found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
This plugin requests these system permissions. Most are normal for its category.
Set these up before or after installing:
Environment variable: ZENDESK_SUBDOMAIN
Add this to your MCP configuration file:
{
"mcpServers": {
"io-github-fruggr-zendesk-mcp-server": {
"env": {
"ZENDESK_SUBDOMAIN": "your-zendesk-subdomain-here"
},
"args": [
"-y",
"@fruggr/zendesk-mcp-server"
],
"command": "npx"
}
}
}From the project's GitHub README.
Bring Zendesk Support & the Help Center into your AI assistant. A Model Context Protocol (MCP) server that lets your assistant search articles, answer questions, and create, track and update tickets in plain language — without switching apps.
Think of it as the Zendesk agent for Microsoft 365 Copilot, but vendor-neutral — it drops into any MCP client (Claude Desktop, Claude Code, Cursor, VS Code, …) instead of being tied to one assistant — and it always acts with each user's own Zendesk permissions, never a shared admin key.
Ask in natural language; the assistant figures out context and intent, then calls the right tools on your behalf:
Because it runs on the user's own OAuth session, the assistant only ever sees and touches what that person is allowed to — the same scoping you'd get signing into Zendesk directly.
Most Zendesk integrations use a shared admin API key, giving every user full access to every ticket, and bolt on a fixed set of tools. This server is built differently:
@modelcontextprotocol/sdk plus zod.Under the hood it speaks to the Zendesk Support & Help Center (Guide) APIs, runs locally over stdio or as a private remote MCP server over HTTP, and ships fine-grained tool-visibility controls — the specifics are below.
Reach for it when:
npx-installable server with no extra infrastructure, or you want to deploy it as a private remote MCP server that web/native clients reach over HTTP — each MCP client still carries its own user's OAuth token.Look elsewhere when:
No API-token authentication. This server is OAuth 2.1 PKCE only — there is no ZENDESK_EMAIL + ZENDESK_API_TOKEN (Basic auth) mode, in any transport. This is a deliberate design choice:
If you specifically need an API-token / service-account mode (e.g. headless CI with a shared account), use one of the other Zendesk MCP servers that support it — see Inspiration & related projects.
| Persona | Transport | Auth | Quick start |
|---|---|---|---|
| Run it on your laptop — single user, plugged into Claude Desktop / Claude Code / VS Code | stdio (default) | OAuth 2.1 PKCE in your browser | Quick start: local |
| Deploy a private remote MCP server — one server per Zendesk account, each MCP client carries its own user's OAuth token | http | Per-user OAuth 2.1 PKCE bearer in Authorization: header | Quick start: remote |
The server registers tools in one of three modes, controlled by --mode:
| Mode | Tools exposed | Best for |
|---|---|---|
all | Every operation as its own tool (get_ticket, search_articles, ...) | Clients with good tool selection, full granularity |
namespace (default) | One proxy tool per namespace (zendesk_tickets, zendesk_help_center, zendesk_users) | Balanced context usage, grouped operations |
single | A single proxy tool (zendesk) | Minimal context footprint, single entry point |
In namespace and single modes, the proxy tool accepts { "operation": "<tool_name>", "params": { ... } } and dispatches to the appropriate handler after validating params through the original Zod schema. Proxy descriptions include only the first sentence of each sub-operation to stay compact; the full schema is applied when the operation is actually called.
Tip: The
singlemode is particularly useful for models with limited tool slots — one tool handles every operation.
--namespace and --read-only apply to every mode (including the default namespace mode) — they filter tools before the proxies are built, so the description of each proxy reflects only the operations that survive the filters. Combine them to register a focused surface:
# Only the Help Center proxy, only read-only operations
zendesk-mcp-server acme --namespace help_center --read-only
# Only the Tickets proxy (read + write)
zendesk-mcp-server acme --namespace tickets
--namespace is repeatable. --tool is also available for cherry-picking individual operations but forces --mode all.
| Tool | Description | Mode |
|---|---|---|
get_ticket | Retrieve a ticket by ID with optional comments and its live SLA state (resolved via a scoped search) | read |
get_ticket_attachments | Download ticket attachments (images as base64, others as references) | read |
search_tickets | Search tickets using Zendesk query syntax, with per-result SLA state | read |
list_tickets | List tickets with cursor-based pagination | read |
get_linked_incidents | Get incidents linked to a problem ticket | read |
list_sla_policies | List SLA policies with filter conditions and per-priority targets (requires an admin token, or a custom role with the SLA-management permission) | read |
create_ticket | Create a new ticket with subject, description, priority, tags... | write |
update_ticket | Update ticket status, priority, assignee, tags, custom fields | write |
add_private_note | Add an internal note (not visible to requester) | write |
add_public_comment | Add a public comment (visible to requester) | write |
manage_tags | Add or remove tags on a ticket | write |
| Tool | Description | Mode |
|---|---|---|
search_articles | Full-text search across Help Center articles | read |
get_article | Retrieve article by ID with full HTML body | read |
get_article_outline | Compact outline of an article (sections + available translations) | read |
get_article_section | Retrieve a single section (html or markdown) | read |
list_categories | List all Help Center categories | read |
list_sections | List sections, optionally filtered by category | read |
list_articles | List articles with sorting and translation info | read |
list_article_translations | List available translations for an article | read |
list_article_attachments | List attachments on an article | read |
list_permission_groups | List Guide permission groups (needed to create articles) | read |
list_content_tags | List Guide content tags (end-user visible) | read |
list_labels | List article labels (search ranking, not user-visible) | read |
list_user_segments | List user segments (article visibility) | read |
compare_translations | Section-level diff between two locales of an article | read |
create_article | Create a new article in a section | write |
update_article | Update article metadata (draft, labels, tags, visibility, section, sort position) | write |
create_article_translation | Create a translation for an article | write |
update_article_translation | Update an article's translation (full body) | write |
update_article_section | Replace a single section of an article | write |
create_content_tag | Create a new Guide content tag | write |
create_article_attachment | Upload an attachment to an article | write |
| Tool | Description | Mode |
|---|---|---|
get_current_user | Get the authenticated user (verify identity) | read |
search_users | Search users by name, email, or query syntax | read |
get_user | Retrieve a user by ID | read |
get_organization | Retrieve an organization by ID | read |
list_organizations | List all organizations with pagination | read |
| Tool | Description | Mode |
|---|---|---|
search | Unified search across tickets, users, and organizations | read |
Beyond tools, the server hands an LLM the structural context it needs to work
against your Help Center — so it stops guessing locales or fuzzy-matching
section names and uses real IDs instead. This is delivered through two
MCP-native channels (both active only when the help_center namespace is, and
disabled together with --no-topology):
instructions (sent on initialize): a short, static blob auto-loaded by
compliant clients. It names the subdomain and points at the topology resource.zendesk-hc://topology (a pull-only MCP resource):
read on demand, it returns Markdown describing the active locales (and the
default), the category → section tree with IDs, the visibility user segments,
the permission groups, and the calling user's role. It is fetched with the
caller's own token, so it respects that user's read permissions. On a very
large Help Center the section tree is summarized (per-category, with a pointer
to list_sections) to stay concise.Clients that don't consume instructions or resources simply ignore them —
the feature degrades silently. Use --no-topology to turn both off server-wide.
package.json#engines.node)Contributors and maintainers run the toolchain on a newer Node + pnpm — see Development.
The default mode. One developer, one Zendesk account, OAuth 2.1 PKCE in the browser.
# Run without installing
npx -y @fruggr/zendesk-mcp-server <your-subdomain>
# Or install globally
npm install -g @fruggr/zendesk-mcp-server
zendesk-mcp-server <your-subdomain>
Cloning from source and running a development branch is covered in the Development section.
<your-subdomain>_zendesk (or set ZENDESK_OAUTH_CLIENT_ID)http://localhost:27439/callback (change the port to match
ZENDESK_OAUTH_CALLBACK_PORT / --callback-port if you override it; Zendesk
accepts several redirect URLs, one per line)zendesk-mcp-server <your-subdomain>
On the first tool call, the server starts the sign-in flow: it opens a browser window and returns a tool message containing the authorize URL. The call does not block waiting for sign-in — authenticate in the browser (or open the URL manually if it didn't open), then retry the request.
Once authenticated, the token is persisted to disk (one owner-only 0600
file per subdomain in your OS config dir —
%APPDATA%\fruggr\zendesk-mcp-server\<subdomain>.json on Windows,
${XDG_CONFIG_HOME:-~/.config}/fruggr/zendesk-mcp-server/<subdomain>.json
elsewhere; override the path with ZENDESK_TOKEN_FILE). It is reused across restarts, so you don't
re-authenticate every time the MCP client respawns the server. If the Zendesk
OAuth client has token expiration enabled, the stored refresh token is used to
renew access silently — proactively (the token is refreshed before use when
it's expired, near expiry, or of unknown age, so the first request after an
overnight gap never hits a visible auth error) and periodically in the
background so a long-lived, idle session never serves a stale token. Only an
expired/invalid refresh token triggers a new browser sign-in.
Port conflict? If port
27439is already in use the first tool call returns a clear error telling you to setZENDESK_OAUTH_CALLBACK_PORT(or--callback-port) to a free port — remember to register the matchinghttp://localhost:<port>/callbackredirect URL in your Zendesk OAuth client.
Add to your claude_desktop_config.json:
{
"mcpServers": {
"zendesk": {
"command": "npx",
"args": ["-y", "@fruggr/zendesk-mcp-server", "<your-subdomain>", "--mode", "single"]
}
}
}
claude mcp add zendesk -- npx -y @fruggr/zendesk-mcp-server <your-subdomain> --mode single
Add to your .vscode/mcp.json:
{
"servers": {
"zendesk": {
"command": "npx",
"args": ["-y", "@fruggr/zendesk-mcp-server", "<your-subdomain>", "--mode", "single"]
}
}
}
🧪 Experimental. The HTTP transport is shipped but has not yet been exercised end-to-end against a real Zendesk tenant from every supported MCP client. Local stdio is the supported path. Until this notice is removed, expect rough edges around OAuth discovery behind reverse proxies, CORS with browser clients, and 401 / refresh flows — please open an issue with the symptoms you hit.
Deploy a private MCP server for one Zendesk account. Every MCP client connecting to the server presents its own user's OAuth bearer in Authorization: — the server never sees a shared admin key.
Same procedure as the local quick start, with one difference: the Redirect URL must match the callback your MCP client uses — provided by the client itself, e.g. https://claude.ai/oauth/callback for claude.ai on the web. Check your client's docs.
zendesk-mcp-server <your-subdomain> --transport http --port 3000 \
--public-url https://mcp.example.com
# stderr: Zendesk MCP server running via http on 0.0.0.0:3000
--public-url (or PUBLIC_URL=…) is the URL clients use to reach you. It's what gets advertised in the OAuth discovery metadata as the canonical resource identifier (RFC 8707). When the server is behind a TLS reverse proxy — Azure App Service, Heroku, Fly.io, Cloudflare Tunnel, nginx, Caddy… — the bind host and the public URL differ, and spec-compliant MCP clients will refuse the connection if the metadata advertises the wrong resource. Without it the server boots in a degraded mode and prints a warning.
| Platform | Recommended setup |
|---|---|
| Azure App Service | Startup command: PUBLIC_URL="https://$WEBSITE_HOSTNAME" zendesk-mcp-server $ZENDESK_SUBDOMAIN --transport http --port $PORT |
| Heroku / Fly / Cloud Run | PUBLIC_URL=https://<your-app>.<provider>.app in the env / config |
| Caddy / nginx / Traefik in front of a VM | PUBLIC_URL=https://mcp.example.com |
| Local dev (no proxy) | --host 127.0.0.1 --port 3000 — the resource URL is derived automatically (the wildcard 0.0.0.0 is what triggers the warning) |
Authorization: Bearer … is required on every /mcp request — a session id alone is never accepted as a credential. The most recent bearer presented on a session is the one used for Zendesk calls, so a client refreshing its token mid-session just works.
Served by the HTTP transport in src/transports/http.ts:
curl -s http://localhost:3000/.well-known/oauth-protected-resource
# → { "authorization_servers": ["https://<subdomain>.zendesk.com"], ... }
curl -s http://localhost:3000/.well-known/oauth-authorization-server
# → { "issuer": "https://<subdomain>.zendesk.com", "authorization_endpoint": "...", ... }
curl -s -i http://localhost:3000/healthz # → 200 OK
Every major MCP client supports remote servers over Streamable HTTP and handles the OAuth 2.1 PKCE discovery flow natively — paste the URL, sign in once, you're connected. Replace https://mcp.example.com below with your deployed origin.
claude mcp add zendesk --transport http https://mcp.example.com/mcp
Settings → Connectors → + Add custom connector, paste https://mcp.example.com/mcp, click Connect. Claude Desktop drives the OAuth flow in your browser on first call.
Settings → Connectors → Add custom connector, same URL. The OAuth flow runs in the same tab.
Add to your .vscode/mcp.json:
{
"servers": {
"zendesk": {
"type": "http",
"url": "https://mcp.example.com/mcp"
}
}
}
Both expose an MCP settings UI that accepts a remote URL. Paste https://mcp.example.com/mcp and sign in when prompted.
Zed added native OAuth 2.0 + PKCE for Streamable HTTP MCP servers in 2026 (zed-industries/zed#51768). Configure the remote server in your Zed settings; on first use Zed opens a loopback browser callback to complete the flow.
If you're on an older Zed build that predates that change, fall back to mcp-remote as a local shim that does the OAuth flow on your machine and proxies the session:
{
"context_servers": {
"zendesk": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://mcp.example.com/mcp"]
}
}
}
On the first call the MCP client fetches the discovery metadata, performs the OAuth 2.1 PKCE flow against Zendesk on behalf of the end user, and sends the resulting access token as a Bearer to the server. Each subsequent tool call runs with that user's Zendesk permissions.
The HTTP transport ships a default CORS allowlist that covers today's major browser-based MCP clients out of the box (ordered by user base): chatgpt.com, claude.ai, gemini.google.com, copilot.microsoft.com, perplexity.ai, chat.mistral.ai, grok.com, plus chat.openai.com. Localhost on any port (MCP Inspector, dev pages) is also always allowed.
Native MCP clients (Claude Desktop / Claude Code CLI / Cursor / VS Code / Zed) send no Origin header — CORS doesn't apply to them, they work regardless.
To allow an additional browser origin (custom dashboard, internal portal), pass --cors-origin (repeatable) or set CORS_ORIGIN as a comma-separated list:
zendesk-mcp-server acme --transport http --port 3000 \
--cors-origin https://internal-dashboard.example.com \
--cors-origin https://team-portal.example.com
The defaults are always applied — your additions extend them, they don't replace them.
This server provides the MCP transport and the OAuth discovery metadata. The operator is still responsible for:
0.0.0.0 by default — choose carefully)zendesk-mcp-server <subdomain> [options]
Options:
--mode <mode> single | namespace (default) | all
--namespace <ns> Filter by namespace (repeatable): tickets, help_center, users
--tool <name> Filter by tool name (repeatable, forces --mode all)
--read-only Only expose read operations
--no-topology Disable the Help Center structural context
(instructions + zendesk-hc://topology resource)
--log-level <level> debug | info (default) | warn | error
--transport <t> stdio (default) | http
--host <host> HTTP bind host (default: 0.0.0.0)
--port <port> HTTP bind port (default: 3000; 0 = OS-assigned)
--public-url <url> Public URL clients use to reach the server (HTTP mode,
required behind a TLS reverse proxy)
--cors-origin <url> Extra browser origin allowed by CORS (repeatable;
adds to the default allowlist of major web MCP
clients + localhost-any-port)
--callback-port <port> Local OAuth callback port for stdio (default 27439)
--namespace and --read-only are applied before the proxies are registered, so they narrow the surface in every mode — in the default namespace mode, --namespace help_center registers a single proxy (zendesk_help_center) instead of three.
Examples:
# Local single-tool mode — minimal context, every operation in one tool
zendesk-mcp-server acme --mode single
# Read-only tickets only
zendesk-mcp-server acme --read-only --namespace tickets
# Cherry-pick specific tools
zendesk-mcp-server acme --tool get_ticket --tool search_tickets --tool get_current_user
# Remote HTTP, read-only Help Center surface
zendesk-mcp-server acme --transport http --port 8080 \
--namespace help_center --read-only
| Variable | Required | Default | Description |
|---|---|---|---|
ZENDESK_SUBDOMAIN | yes (or CLI arg) | — | Zendesk subdomain (e.g., acme for acme.zendesk.com) |
ZENDESK_OAUTH_CLIENT_ID | no | <subdomain>_zendesk | OAuth client identifier |
ZENDESK_OAUTH_CALLBACK_PORT | no | 27439 | Local port for the OAuth browser callback (also --callback-port). Must match the redirect URL registered in Zendesk. stdio only. |
ZENDESK_TOKEN_FILE | no | OS config dir | Path to the persisted OAuth token file (0600). |
TRANSPORT | no | stdio | stdio or http |
HOST | no | 0.0.0.0 | HTTP bind host |
PORT | no | 3000 | HTTP bind port (0 to let the OS pick) |
PUBLIC_URL | recommended in HTTP behind a proxy | derived from host:port | Public URL advertised in OAuth discovery metadata |
CORS_ORIGIN | no | — | Comma-separated browser origins added to the default CORS allowlist |
LOG_LEVEL | no | info | Log verbosity (debug surfaces the full OAuth flow trace) |
The server uses per-user OAuth 2.1 PKCE for every transport (local stdio and remote HTTP). There is no static API-token mode — see What this server does not do.
The OAuth flow opens your default browser on the first tool call. The first call fails fast with a message that includes the authorize URL, so even if the browser can't open (common in sandboxed or remote desktop environments) you can open that URL manually — it's also printed to the server's stderr. Sign in, then retry the request.
To collect diagnostics, restart with LOG_LEVEL=debug. The server then emits
structured logs through two channels, so they're reachable on any MCP client:
notifications/message) — surfaced by clients
that support the logging capability.When the browser fails to open, look for the oauth_browser_open_failed event:
it reports the underlying error, the platform, and which environment markers are
present (no secrets, tokens, or env values are ever logged).
The sign-in flow runs a short-lived local server on port 27439 to receive the
callback. If that port is taken, the first tool call fails with a message saying
so (and logs oauth_callback_listen_failed). Pick a free port with
ZENDESK_OAUTH_CALLBACK_PORT=<port> (or --callback-port <port>), and register
the matching http://localhost:<port>/callback redirect URL in your Zendesk
OAuth client.
The OAuth token is persisted to an owner-only file in your OS config dir and
reused across restarts, so this shouldn't happen. If it does, check that the file
is writable (ZENDESK_TOKEN_FILE to relocate it) and look for
token_persist_failed in the logs.
Where each client writes the server's stderr:
| Client | Log location |
|---|---|
| Claude Desktop (macOS) | ~/Library/Logs/Claude/mcp-server-*.log |
| Claude Desktop (Windows) | %APPDATA%\Claude\logs\mcp-server-*.log |
| Claude Code | claude --debug, or the session logs |
| Cursor / VS Code / Cline | the extension's MCP output/log panel |
| Tool | Version | Source of truth |
|---|---|---|
| Node | 24 | .nvmrc — read by nvm, fnm, mise, asdf, volta |
| pnpm | 11 | package.json#packageManager (pinned with a corepack integrity hash) |
The toolchain (Node 24 + pnpm 11) is used to build, lint, type-check and
test the project. The published package still runs on Node 20+ (see
engines.node); a dedicated CI job installs the packed tarball on Node 20
and runs the smoke test to keep that promise honest.
# Clone, install, build
git clone https://github.com/fruggr/zendesk-mcp-server.git
cd zendesk-mcp-server && pnpm install && pnpm build
node dist/index.js <your-subdomain>
# Dev mode, OAuth (browser opens on first tool call)
pnpm dev -- <your-subdomain> --mode all
# Dev mode, HTTP transport (OAuth bearer from the MCP client)
pnpm dev -- <your-subdomain> --transport http --port 3000 --public-url http://localhost:3000
# Build / typecheck / lint / test
pnpm build && pnpm typecheck && pnpm check && pnpm test
To test a PR branch without publishing to npm — the prepare script builds on install:
npx -y github:fruggr/zendesk-mcp-server <your-subdomain>
npx -y github:fruggr/zendesk-mcp-server#my-feature-branch <your-subdomain>
Contributor conventions (architecture, code style, submission bar, release workflow) live in AGENTS.md.
This project was built with reference to:
Versions follow SemVer and are calculated automatically from commit messages — no one bumps the version by hand. Every merge to main triggers semantic-release, which inspects the new Conventional Commits since the previous tag, computes the next version, updates CHANGELOG.md, publishes to npm, creates the matching GitHub Release, and mirrors the release into the official MCP registry as io.github.fruggr/zendesk-mcp-server so registry-driven clients discover the new version automatically.
| Commit type | Resulting bump |
|---|---|
fix:, perf: | patch |
feat: | minor |
feat!:, fix!:, or a BREAKING CHANGE: footer | major |
docs:, chore:, refactor:, test:, ci:, style:, build: | no release |
Do I need a Zendesk admin API key? No — and the server doesn't support one. The OAuth 2.1 PKCE flow means each user authenticates with their own credentials and the server acts with exactly their permissions. Static API tokens are intentionally unsupported (see What this server does not do).
Which Zendesk products are supported? Zendesk Support (tickets, users, organizations) and the Help Center / Guide (articles, sections, categories, translations, labels, content tags, segments, attachments). Talk, Explore, and Sell are out of scope.
How do I keep the model's context small?
Use --mode single (one zendesk tool) or --mode namespace (three proxies),
and --read-only to drop write operations. For big articles, the section-based
tools (get_article_outline, get_article_section, update_article_section)
let the model touch one section at a time instead of the whole HTML body.
Can I restrict it to read-only?
Yes — pass --read-only and every write tool is filtered out before the proxies
are built, in any mode.
Which Node.js version do I need?
Node.js >= 20 to run the published package (engines.node). The dev toolchain
uses a newer Node — see Development.
The OAuth browser window didn't open. What now?
The authorization URL is also printed to stderr — open it manually. Restart with
LOG_LEVEL=debug for the full flow trace. See
Troubleshooting.
Is it safe to run via npx?
Releases are published from CI via npm Trusted Publishing (OIDC), so each version
carries a build provenance attestation you can verify on its
npm page. No secrets
are ever logged by the server.
Pull requests are welcome — including AI-assisted ones, as long as the human author has read and validated every line.
The full guide is in CONTRIBUTING.md. The short version:
main.pnpm check, pnpm typecheck, and pnpm test pass locally.Every PR is reviewed automatically by CodeRabbit in CI, on top of the author-side AI review. The project is maintained in part with Claude Code assistance; that workflow is documented in CONTRIBUTING.md.
Built and maintained by Digital4better for the Fruggr project.
Be the first to review this server!
by Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
by mcp-marketplace · Developer Tools
Create, build, and publish Python MCP servers to PyPI — conversationally.
by Microsoft · Content & Media
Convert files (PDF, Word, Excel, images, audio) to Markdown for LLM consumption