omaralsayeed/zendesk-mcp-ts

Zendesk MCP

A production-ready MCP (Model Context Protocol) server that exposes Zendesk administrative and configuration capabilities to AI assistants like Cursor and Claude Desktop.

Built with TypeScript, the official MCP SDK, and Axios. Includes resilient networking (retry/backoff with Retry-After), typed endpoints, and a clean ESM build for npx.

Highlights

• MCP tools for Zendesk: users, ticket fields/forms, account settings, user/org fields, triggers, views, dynamic content, macros
• Resilient HTTP: 15s timeouts, exponential backoff, 429/5xx retries, honors Retry-After
• Typed: strict TypeScript models for safer usage
• Secure logging: Pino with secret redaction
• npx-ready: single CLI entry for easy Cursor integration

Quick start

1. Requirements

• Node.js 18+
• Zendesk subdomain, email, and API token

2. Environment Create a .env in the project root:

ZENDESK_SUBDOMAIN=your-subdomain
ZENDESK_EMAIL=your-email@example.com
ZENDESK_API_TOKEN=your-api-token
# Optional
LOG_LEVEL=info

3. Run locally

npm install
npm run build
node dist/server.js

You should see a stderr line like: zendesk-mcp started.

Use with Cursor (via npx)

Add to Cursor settings → Features → MCP Servers:

{
  "mcpServers": {
    "zendesk-mcp": {
      "command": "npx",
      "args": ["-y", "@omaralsayeed/zendesk-mcp"],
      "env": {
        "ZENDESK_SUBDOMAIN": "your-subdomain",
        "ZENDESK_EMAIL": "your-email@example.com",
        "ZENDESK_API_TOKEN": "your-api-token"
      }
    }
  }
}

After saving, tools are available to the assistant and via the command palette.

Tools (examples)

• zendesk.get_users — list users
• zendesk.get_ticket_fields — list ticket fields
• zendesk.create_ticket_field — create a ticket field
  • New: zendesk.count_ticket_fields, zendesk.show_ticket_field
  • New: zendesk.list_ticket_field_options, zendesk.show_ticket_field_option
  • New: zendesk.create_ticket_field_option, zendesk.update_ticket_field, zendesk.delete_ticket_field_option, zendesk.delete_ticket_field
• Ticket Forms — list/get/update/reorder/manage statuses
  • New: zendesk.create_ticket_form
• Account Settings — show/update
• User/Organization Fields — list/reorder
• Triggers — bulk update (incl. custom objects)
• Views — bulk update
• Dynamic Content — show/update/delete items; manage variants
• Macros — bulk delete, upload unassociated macro attachment

Outputs are structured (JSON/text) and errors include clear context.

Programmatic usage examples (Node)

Ensure env vars are set (ZENDESK_SUBDOMAIN, ZENDESK_EMAIL, ZENDESK_API_TOKEN). Then:

Count ticket fields:

node -e "(async()=>{const e=require('./dist/lib/endpointsFunctions.js');const c=await e.countTicketFields();console.log({count:c});})()"

List field options:

node -e "(async()=>{const e=require('./dist/lib/endpointsFunctions.js');const o=await e.listTicketFieldOptions(38957073274385);console.log(o);})()"

Add option "Rejected" to field 38957073274385:

node -e "(async()=>{const e=require('./dist/lib/endpointsFunctions.js');const r=await e.createTicketFieldOption(38957073274385,{name:'Rejected',value:'rejected',default:false});console.log(r);})()"

Create a ticket form:

node -e "(async()=>{const e=require('./dist/lib/endpointsFunctions.js');const f=await e.createTicketForm({name:'Support Requests',display_name:'Support Requests',ticket_field_ids:[]});console.log(f);})()"

How it works

• src/server.ts: MCP server startup (stdio) and tool registration
• src/tools/**: tool definitions/handlers grouped by Zendesk area
• src/resources/**: thin wrappers for Zendesk endpoints
• src/lib/zendeskClient.ts: Axios client with:
  • base URL from env
  • 15s timeout
  • retries for 429/5xx and network timeouts
  • Retry-After support and clear error summaries
• src/types/**: TypeScript models
• src/lib/logger.ts: Pino + redaction

Development

• Install: npm install
• Build: npm run build
• Dev run: npm run dev

Project layout:

src/
  lib/                # axios client, logger, endpoint aggregator
  resources/          # resource wrappers (users, tickets, forms, etc.)
  tools/              # MCP tool registration + handlers
  types/              # Zendesk models
  server.ts           # MCP server (stdio)
config/
  mcp-config.json     # example (optional)

Publishing (maintainers)

• Ensure package.json includes:
  • "type": "module"
  • "bin": { "zendesk-mcp": "./dist/server.js" }
  • "files": ["dist/**", "README.md", "LICENSE"]
  • description, keywords, repository, author
• Build: npm run build
• Publish: npm publish --access public

Consumers can run:

npx -y @omaralsayeed/zendesk-mcp

Troubleshooting

• Tools not visible in Cursor
  • Validate JSON config and that npx is allowed
  • Ensure env vars are set in the Cursor config
• 401/403/422
  • Verify API token and that /token auth is supported in your plan
• Rate limit 429
  • The client retries and honors Retry-After, but heavy write workloads may still throttle
• Windows paths
  • .env resolution uses process.cwd(). Start from the project root or ensure .env is there

Security

• Secrets are redacted from logs
• Report issues via GitHub or email in package.json

License

MIT © Omar Al Sayeed