@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 — optional OAuth client ID for legacy token refresh flows
• ZENDESK_CLIENT_SECRET — optional OAuth client secret for legacy token refresh flows
• 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

Standalone config directory

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.
• 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

| Symptom | Likely cause | Fix | |---------|--------------|-----| | Connector fails to start | Not built yet | Run npm install && npm run build | | Auth error or empty results | Wrong config path or invalid credentials | Check ZENDESK_CONFIG_PATH and accounts.json | | MCP host reports protocol issues | Stdout noise in stdio session | Ensure no console.log calls (all logging uses console.error) |

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.