Zendesk MCP Server (TypeScript)

A Model Context Protocol (MCP) server for searching Zendesk tickets. Install with npm install -g zendesk-mcp-ts and use with npx zendesk-mcp-ts in your AI coding assistants.

Features

• 🔍 Search tickets using Zendesk's powerful search API
• 📄 Pagination support with configurable page size
• 🔄 Sorting capabilities (by date, priority, status, etc.)
• 🏢 Organization details fetching with batch processing
• ⚡ Fast and efficient TypeScript implementation
• 🛡️ Type-safe with strict readonly types and Zod validation
• 🔧 Easy configuration via environment variables
• 🚀 Optimized async operations with retry logic
• 📊 Comprehensive error handling with detailed messages
• 🔍 Enhanced logging and debugging capabilities
• 📡 stdio transport for seamless MCP integration
• 🤖 Compatible with Claude Desktop, Cursor, Cline, and other MCP clients

Installation

Global Installation (Recommended)

npm install -g zendesk-mcp-ts

Using NPX (No Installation)

npx zendesk-mcp-ts

Development Setup

git clone <repository-url>
cd zendesk-mcp-ts
npm install
npm run build
npm start

Configuration

Create a .env file in your project root with the following variables:

ZENDESK_SUBDOMAIN=your-subdomain
[email protected]
ZENDESK_API_TOKEN=your-api-token

Getting Your API Token

1. Go to your Zendesk Admin Center
2. Navigate to Apps and integrations > APIs > Zendesk API
3. Generate a new API token
4. Copy the token to your .env file

Quick Start

1. Install

npm install -g zendesk-mcp-ts

2. Configure Environment

export ZENDESK_SUBDOMAIN="your-subdomain"
export ZENDESK_EMAIL="[email protected]"
export ZENDESK_API_TOKEN="your-api-token"

3. Use with AI Assistants

See the AI Coding Assistants section below for configuration.

Usage with AI Coding Assistants

Claude Desktop

{
  "mcpServers": {
    "zendesk": {
      "command": "npx",
      "args": ["zendesk-mcp-ts"],
      "env": {
        "ZENDESK_SUBDOMAIN": "your-subdomain",
        "ZENDESK_EMAIL": "[email protected]",
        "ZENDESK_API_TOKEN": "your-api-token"
      }
    }
  }
}

Cursor IDE

{
  "mcpServers": {
    "zendesk": {
      "command": "npx",
      "args": ["zendesk-mcp-ts"],
      "env": {
        "ZENDESK_SUBDOMAIN": "your-subdomain",
        "ZENDESK_EMAIL": "[email protected]",
        "ZENDESK_API_TOKEN": "your-api-token"
      }
    }
  }
}

Cline (VS Code Extension)

{
  "cline.mcpServers": {
    "zendesk": {
      "command": "npx",
      "args": ["zendesk-mcp-ts"],
      "env": {
        "ZENDESK_SUBDOMAIN": "your-subdomain",
        "ZENDESK_EMAIL": "[email protected]",
        "ZENDESK_API_TOKEN": "your-api-token"
      }
    }
  }
}

GitHub Copilot (VS Code)

Install the Copilot MCP extension and add:

{
  "mcpServers": {
    "zendesk": {
      "command": "npx",
      "args": ["zendesk-mcp-ts"],
      "env": {
        "ZENDESK_SUBDOMAIN": "your-subdomain",
        "ZENDESK_EMAIL": "[email protected]",
        "ZENDESK_API_TOKEN": "your-api-token"
      }
    }
  }
}

Other MCP Clients

{
  "command": "npx",
  "args": ["zendesk-mcp-ts"],
  "env": {
    "ZENDESK_SUBDOMAIN": "your-subdomain",
    "ZENDESK_EMAIL": "[email protected]",
    "ZENDESK_API_TOKEN": "your-api-token"
  }
}

Available Tools

search_tickets

Search for tickets in Zendesk using the search API.

Parameters:

• query (required): Search query with Zendesk operators
• sort_by (optional): Field to sort by (e.g., "created_at", "updated_at", "priority")
• sort_order (optional): Sort order - "asc" or "desc" (default: "asc")
• per_page (optional): Number of results per page, max 100 (default: 25)
• page (optional): Page number to retrieve (default: 1)

Example Queries:

• type:ticket status:open - Open tickets
• created>2025-01-01 - Tickets created after January 1, 2025
• assignee:[email protected] - Tickets assigned to specific user
• tags:urgent - Tickets with "urgent" tag
• status:open priority:high - High priority open tickets

Troubleshooting

Test the server:

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "search_tickets", "arguments": {"query": "status:open"}}}' | npx zendesk-mcp-ts

Debug mode:

DEBUG=* npx zendesk-mcp-ts

Development

Scripts

• npm run build - Build the TypeScript code
• npm start - Run the built application
• npm run dev - Run in development mode with tsx
• npm run watch - Run in watch mode with nodemon

Project Structure

src/
├── index.ts              # Main entry point
├── server.ts             # MCP server implementation
├── client.ts             # Zendesk API client
├── models.ts             # TypeScript interfaces
├── tools/
│   ├── searchTickets.ts  # Search tickets tool
│   └── index.ts          # Tool exports
└── utils/
    └── validation.ts     # Zod schemas

License

MIT License - see LICENSE file for details.