Zendesk

@mindstone/mcp-server-zendesk

Zendesk Support MCP server — tickets, users, comments, macros, account setup, and support-workflow discovery through a standard stdio MCP package.

Best for support teams that want an assistant to triage, summarize, and update Zendesk tickets from a local MCP host.

Status

• Version: 0.4.1 · npm
• Auth: Hybrid (API token or OAuth) (ZENDESK_CLIENT_SECRET)
• Tools: 26 (tickets, users, comments, macros, views, help center, satisfaction)
• Surface: cloud-api
• Machine-readable: STATUS.json

Why this exists

Zendesk has announced its own MCP client and server experiences for broader platform integration. This package is for MCP hosts that want a local Zendesk Support connector they can install and run directly.

It helps an assistant do the support work humans usually ask for: find urgent tickets, pull the latest context, draft or add comments, apply macros, look up users and organizations, and inspect support setup. The benefit is faster ticket triage and follow-up while treating customer-authored ticket text as something to quote and summarize, not as instructions to obey.

Example interaction

"Find high-priority open Zendesk tickets and show me the latest details for the first one."

Tools the host calls:

1. search_zendesk_tickets — searches type:ticket status:open priority:high and returns ticket summaries.
2. get_zendesk_ticket — fetches the selected ticket, including wrapped subject and description text.

Response (trimmed):

{
  "ok": true,
  "ticket": {
    "id": 12345,
    "status": "open",
    "priority": "high",
    "subject": "<untrusted-content source=\"external-ticket\">Login issue</untrusted-content>",
    "description": "<untrusted-content source=\"external-ticket\">Customer cannot access the admin dashboard.</untrusted-content>"
  }
}

Requirements

• Node.js 20+
• npm

One-click install

After clicking the button, your host will prompt you to fill: ZENDESK_CONFIG_PATH, ZENDESK_CLIENT_SECRET.

{
  "mcpServers": {
    "Zendesk": {
      "command": "npx",
      "args": [
        "-y",
        "@mindstone/mcp-server-zendesk"
      ],
      "env": {
        "ZENDESK_CONFIG_PATH": "~/.mcp/zendesk",
        "ZENDESK_CLIENT_SECRET": ""
      }
    }
  }
}

Quick Start

Install & build

cd <path-to-repo>/connectors/zendesk
npm install
npm run build

npx (once published)

npx -y @mindstone/mcp-server-zendesk

Local

node dist/index.js

Configuration

Environment variables

• ZENDESK_CONFIG_PATH — path to the config directory that contains accounts.json and credentials/
• ZENDESK_CLIENT_ID — OAuth client ID used to renew sign-ins whose token file doesn't carry its own client_id; read when a refresh happens
• ZENDESK_CLIENT_SECRET — only for confidential OAuth clients, and only sent together with ZENDESK_CLIENT_ID; public (PKCE) clients need none
• MCP_HOST_BRIDGE_STATE — optional path to a host bridge state file used for credential management
• MINDSTONE_REBEL_BRIDGE_STATE — backwards-compatible alias for MCP_HOST_BRIDGE_STATE

Authentication

Each account uses one of two kinds of credential. For a given subdomain, an OAuth sign-in wins over an API token.

OAuth sign-in (preferred). The host app runs the Zendesk sign-in (for example, an authorization-code flow with PKCE) and writes the result to credentials/<subdomain>.token.json under ZENDESK_CONFIG_PATH, owner-only (0600):

{
  "access_token": "…",
  "refresh_token": "…",
  "expires_in": 1800,
  "expires_at": 1767225600000,
  "token_type": "bearer",
  "subdomain": "acme",
  "email": "[email protected]",
  "client_id": "your-oauth-client-id",
  "scope": "read write"
}

expires_at is a millisecond timestamp. client_id and scope are optional; when present, refreshes use that client and ask for the same scope.

The connector renews the access token itself, within five minutes of expiry or after a 401:

• It sends a JSON request to https://<subdomain>.zendesk.com/oauth/tokens with the refresh token and the client id (the token file's client_id, else ZENDESK_CLIENT_ID). No client secret is needed for a public client.
• Concurrent tool calls share one refresh, and the token file is re-read first, so a token renewed by another process is used rather than spent again.
• The rotated refresh token is saved by replacing the file atomically, and only if the file still holds the refresh token that was just spent. A token file that was removed while a refresh was running (the account was disconnected) is not recreated, and one replaced by a new sign-in is kept and used instead.
• If the renewed token can't be saved (a full or read-only disk), the connector keeps using it in memory and doesn't send the spent refresh token again; list_zendesk_accounts shows a warning on that account until the file changes. After a restart, the account may need to sign in again.
• If Zendesk refuses the refresh token (invalid_grant, invalid_client, unauthorized_client), or there is no client id, tool calls fail with AUTH_FAILED and "Reconnect Zendesk…", and list_zendesk_accounts reports reconnect-required. The token file is kept; signing in again replaces it.
• A temporary failure (server error, rate limit, network) returns AUTH_REFRESH_FAILED ("try again in a moment") once the access token has expired; the next call tries again.

API token. An entry with subdomain, email and apiToken in accounts.json (see below), sent as HTTP Basic auth. API tokens don't expire, so they are always active.

Standalone config directory

To use an API token, create a config directory and accounts.json file:

mkdir -p ~/.mcp/zendesk
cat > ~/.mcp/zendesk/accounts.json <<'EOF'
{
  "accounts": [
    {
      "subdomain": "yourcompany",
      "email": "[email protected]",
      "apiToken": "your-zendesk-api-token"
    }
  ],
  "defaultSubdomain": "yourcompany"
}
EOF

Host configuration examples

Claude Desktop / Cursor

{
  "mcpServers": {
    "Zendesk": {
      "command": "npx",
      "args": ["-y", "@mindstone/mcp-server-zendesk"],
      "env": {
        "ZENDESK_CONFIG_PATH": "~/.mcp/zendesk"
      }
    }
  }
}

Local development (no npm publish needed)

{
  "mcpServers": {
    "Zendesk": {
      "command": "node",
      "args": ["<path-to-repo>/connectors/zendesk/dist/index.js"],
      "env": {
        "ZENDESK_CONFIG_PATH": "~/.mcp/zendesk"
      }
    }
  }
}

Mindstone Rebel

"Zendesk": {
  "name": "Zendesk",
  "type": "stdio",
  "command": "node",
  "args": ["<path-to-repo>/connectors/zendesk/dist/index.js"],
  "env": {
    "ZENDESK_CONFIG_PATH": "~/Library/Application Support/mindstone-rebel/mcp/zendesk",
    "MCP_HOST_BRIDGE_STATE": "~/Library/Application Support/mindstone-rebel/mcp/rebel-inbox-bridge.json"
  },
  "description": "Zendesk support tickets...",
  "catalogId": "bundled-zendesk"
}

Tools (26)

Account management

• list_zendesk_accounts — List connected accounts with auth status
• remove_zendesk_account — Disconnect a Zendesk account
• authenticate_zendesk_account — Connect using API token

Tickets

• search_zendesk_tickets — Search with Zendesk query syntax (max 1000 results)
• export_zendesk_tickets — Cursor-based export with no 1000-result limit
• get_zendesk_ticket — Get single ticket by ID
• get_zendesk_tickets_by_ids — Batch-fetch multiple tickets
• create_zendesk_ticket — Create a new ticket
• update_zendesk_ticket — Update ticket fields, status, or add comment

Users

• search_zendesk_users — Search by name, email, or query
• get_zendesk_user — Get user by ID
• create_or_update_zendesk_user — Create a user or update the one with the same email

Comments

• list_zendesk_ticket_comments — List conversation thread with author resolution
• add_zendesk_ticket_comment — Add public reply or internal note

Discovery

• list_zendesk_groups — List agent groups
• list_zendesk_ticket_fields — List ticket fields including custom fields
• list_zendesk_views — List saved ticket views
• list_zendesk_view_tickets — Execute a view and list its tickets
• list_zendesk_organizations — List organizations
• get_zendesk_organization — Get a single organization by ID

Macros

• list_zendesk_macros — List or search macros
• get_zendesk_macro — Get macro details
• apply_zendesk_macro — Preview and apply macro to ticket

Help Center

• search_zendesk_help_center_articles — Search knowledge-base articles
• get_zendesk_help_center_article — Read a full Help Center article

Satisfaction

• list_zendesk_satisfaction_ratings — List CSAT ratings with score/date filters

Security notes

• Zendesk API-token credentials live in accounts.json; OAuth credentials are read from credentials/*.token.json under ZENDESK_CONFIG_PATH. Renewed tokens are written to a 0600 temp file in the same folder and renamed into place; token files are never deleted on a failed refresh.
• Access tokens, refresh tokens and the token endpoint's error descriptions are never logged; only HTTP status and OAuth error codes are.
• Host bridge calls, when configured, go to 127.0.0.1 using the token from MCP_HOST_BRIDGE_STATE.
• Ticket subjects, descriptions, comment bodies, user/org/group/macro/view/field text, and other externally authored strings are wrapped in <untrusted-content source="...">...</untrusted-content> envelopes with close-tag escaping before model exposure.
• Ticket exports that write files are constrained to the system temp directory (symlink-safe canonical containment) and are created inside a fresh private per-export directory with owner-only permissions — only the requested file name is honoured, the full path is returned as file_path, and pre-existing files are never touched. export_zendesk_tickets and get_zendesk_tickets_by_ids are annotated as non-read-only because they can write local export files.
• Email inputs are validated for format and phone inputs for E.164 before any network call; numeric IDs and pagination parameters must be positive integers.
• Account removal, ticket updates, ticket comments, and macro application are marked so capable hosts can ask before changing support data.

Smoke test

Ask your MCP host to run:

List my open Zendesk tickets

If that fails, confirm that:

• dist/index.js exists (run npm run build)
• ZENDESK_CONFIG_PATH points to a readable directory
• accounts.json contains a valid subdomain, email, and API token

Troubleshooting

Licence

FSL-1.1-MIT — Functional Source License, Version 1.1, with MIT future licence. The software converts to MIT licence on 2030-04-08.