npm package: @omaralsayeed/zendesk-mcp
Description: MCP (Model Context Protocol) server exposing Zendesk admin and configuration tools for AI assistants (Cursor, Claude Desktop).
Author: Omar Al Sayeed
Latest version: 1.0.4

### 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:

```json
{
  "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