Jake Shore 2d0db0f147 zendesk: 89 tools, 13 apps, comprehensive README

- Fixed TypeScript compilation errors in clients/zendesk.ts and types/index.ts
- Added comprehensive README.md with:
  - Complete tool reference (89 unique tools across 16 categories)
  - 13 React UI app descriptions and use cases
  - Architecture diagram
  - Setup and usage examples
  - Development guide
- Verified package.json has proper bin, build, and prepublishOnly scripts
- All TypeScript checks passing (npm run typecheck)

2026-02-12 17:13:40 -05:00

23 KiB

Raw Blame History

Zendesk MCP Server

A comprehensive Model Context Protocol (MCP) server providing complete coverage of the Zendesk Support API with 89 tools across 16 functional areas, plus 13 rich React UI applications for interactive data exploration and management.

🌟 Features

Complete API Coverage: 89 MCP tools spanning tickets, users, organizations, groups, tags, brands, triggers, macros, automations, views, custom fields, SLA policies, satisfaction ratings, suspended tickets, and search
Rich UI Applications: 13 interactive React apps for dashboards, detail views, and data grids
Automatic Pagination: Cursor-based and URL-based pagination handled transparently
Rate Limit Awareness: Built-in rate limiting to respect Zendesk API quotas
TypeScript: Full type safety with comprehensive TypeScript definitions
Dual Authentication: Support for both OAuth tokens and API token authentication

📦 Installation

npm install -g @mcpengine/zendesk-mcp-server

Or use directly with npx:

npx @mcpengine/zendesk-mcp-server

🚀 Quick Start

Configuration

The server requires Zendesk credentials. You can authenticate using either:

Option 1: API Token (recommended)

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

Option 2: OAuth Token

{
  "mcpServers": {
    "zendesk": {
      "command": "npx",
      "args": ["-y", "@mcpengine/zendesk-mcp-server"],
      "env": {
        "ZENDESK_SUBDOMAIN": "your-subdomain",
        "ZENDESK_OAUTH_TOKEN": "your-oauth-token"
      }
    }
  }
}

Getting Your API Token

Go to Admin → Channels → API
Enable token access
Click "Add API token"
Copy the generated token
Your subdomain is the part before .zendesk.com in your Zendesk URL

Running the Server

# With environment variables
ZENDESK_SUBDOMAIN=yourcompany \
ZENDESK_EMAIL=admin@yourcompany.com \
ZENDESK_API_TOKEN=your_token \
zendesk-mcp

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                     MCP Client (Claude, etc.)                │
└────────────────────────┬────────────────────────────────────┘
                         │ MCP Protocol
┌────────────────────────▼────────────────────────────────────┐
│                   Zendesk MCP Server                         │
│  ┌──────────────────────────────────────────────────────┐   │
│  │              Server Layer (server.ts)                 │   │
│  │  - Tool registration & routing                        │   │
│  │  - App registration & serving                         │   │
│  │  - Request validation                                 │   │
│  └────────────┬─────────────────────────┬─────────────────┘  │
│               │                         │                    │
│  ┌────────────▼────────────┐  ┌─────────▼──────────────┐    │
│  │   16 Tool Categories    │  │   13 React UI Apps     │    │
│  │  - tickets-tools        │  │  - ticket-dashboard    │    │
│  │  - users-tools          │  │  - sla-dashboard       │    │
│  │  - organizations-tools  │  │  - ticket-detail       │    │
│  │  - groups-tools         │  │  - search-results      │    │
│  │  - tags-tools           │  │  - ticket-grid         │    │
│  │  - brands-tools         │  │  - org-detail          │    │
│  │  - triggers-tools       │  │  - suspended-tickets   │    │
│  │  - macros-tools         │  │  - satisfaction-dash.  │    │
│  │  - automations-tools    │  │  - org-grid            │    │
│  │  - views-tools          │  │  - user-detail         │    │
│  │  - custom-fields-tools  │  │  - macro-manager       │    │
│  │  - sla-tools            │  │  - view-executor       │    │
│  │  - satisfaction-tools   │  │  - user-grid           │    │
│  │  - suspended-tickets-t. │  └────────────────────────┘    │
│  │  - search-tools         │                                │
│  │  (89 total tools)       │                                │
│  └────────────┬─────────────┘                                │
│               │                                              │
│  ┌────────────▼─────────────────────────────────────────┐   │
│  │          ZendeskClient (clients/zendesk.ts)          │   │
│  │  - HTTP request handling                             │   │
│  │  - Authentication (OAuth / API Token)                │   │
│  │  - Rate limiting                                     │   │
│  │  - Automatic pagination                              │   │
│  │  - Error handling                                    │   │
│  └────────────┬─────────────────────────────────────────┘   │
└───────────────┼──────────────────────────────────────────────┘
                │ HTTPS
┌───────────────▼──────────────────────────────────────────────┐
│              Zendesk Support API (v2)                        │
│  https://yoursubdomain.zendesk.com/api/v2                    │
└──────────────────────────────────────────────────────────────┘

🛠️ Complete Tool Reference

Ticket Operations (14 tools)

zendesk_list_tickets - List all tickets with filtering
zendesk_get_ticket - Get detailed ticket information
zendesk_create_ticket - Create a new support ticket
zendesk_update_ticket - Update ticket fields and status
zendesk_delete_ticket - Delete a ticket
zendesk_bulk_update_tickets - Update multiple tickets at once
zendesk_merge_tickets - Merge multiple tickets into one
zendesk_add_ticket_tags - Add tags to a ticket
zendesk_remove_ticket_tags - Remove tags from a ticket
zendesk_add_ticket_comment - Add a comment to a ticket
zendesk_list_ticket_comments - List all comments on a ticket
zendesk_list_ticket_forms - List available ticket forms
zendesk_get_ticket_form - Get ticket form details
zendesk_get_satisfaction_rating - Get CSAT rating for a ticket

User Operations (10 tools)

zendesk_list_users - List all users with pagination
zendesk_get_user - Get detailed user information
zendesk_create_user - Create a new user
zendesk_update_user - Update user profile
zendesk_delete_user - Delete a user
zendesk_search_users - Search users by query
zendesk_merge_users - Merge duplicate user accounts
zendesk_list_user_identities - List user's email/phone identities
zendesk_set_user_password - Set or reset user password
zendesk_get_user_related - Get user's tickets and requests

Organization Operations (8 tools)

zendesk_list_organizations - List all organizations
zendesk_get_organization - Get organization details
zendesk_create_organization - Create a new organization
zendesk_update_organization - Update organization info
zendesk_delete_organization - Delete an organization
zendesk_search_organizations - Search organizations by query
zendesk_list_organization_memberships - List org memberships
zendesk_create_organization_membership - Add user to org

Group Operations (6 tools)

zendesk_list_groups - List all agent groups
zendesk_get_group - Get group details
zendesk_create_group - Create a new group
zendesk_update_group - Update group information
zendesk_delete_group - Delete a group
zendesk_list_group_memberships - List members of a group

Macro Operations (6 tools)

zendesk_list_macros - List all macros
zendesk_get_macro - Get macro details
zendesk_apply_macro - Apply macro to ticket(s)
zendesk_create_macro - Create a new macro
zendesk_update_macro - Update existing macro
zendesk_delete_macro - Delete a macro

Trigger Operations (6 tools)

zendesk_list_triggers - List all triggers
zendesk_get_trigger - Get trigger details
zendesk_create_trigger - Create a new trigger
zendesk_update_trigger - Update trigger configuration
zendesk_delete_trigger - Delete a trigger
zendesk_reorder_triggers - Change trigger execution order

View Operations (7 tools)

zendesk_list_views - List all views
zendesk_get_view - Get view configuration
zendesk_create_view - Create a new view
zendesk_update_view - Update view filters/columns
zendesk_delete_view - Delete a view
zendesk_execute_view - Execute view and get results
zendesk_count_view - Get ticket count for a view

Automation Operations (5 tools)

zendesk_list_automations - List all automations
zendesk_get_automation - Get automation details
zendesk_create_automation - Create a new automation
zendesk_update_automation - Update automation rules
zendesk_delete_automation - Delete an automation

SLA Policy Operations (5 tools)

zendesk_list_sla_policies - List all SLA policies
zendesk_get_sla_policy - Get SLA policy details
zendesk_create_sla_policy - Create a new SLA policy
zendesk_update_sla_policy - Update SLA policy rules
zendesk_delete_sla_policy - Delete an SLA policy

Custom Field Operations (9 tools)

zendesk_list_ticket_fields - List ticket custom fields
zendesk_get_ticket_field - Get ticket field details
zendesk_create_ticket_field - Create new ticket field
zendesk_update_ticket_field - Update ticket field config
zendesk_delete_ticket_field - Delete a ticket field
zendesk_list_user_fields - List user custom fields
zendesk_get_user_field - Get user field details
zendesk_list_organization_fields - List org custom fields
zendesk_get_organization_field - Get org field details

Brand Operations (4 tools)

zendesk_list_brands - List all brands
zendesk_get_brand - Get brand details
zendesk_create_brand - Create a new brand
zendesk_update_brand - Update brand settings

Suspended Ticket Operations (4 tools)

zendesk_list_suspended_tickets - List suspended tickets
zendesk_get_suspended_ticket - Get suspended ticket details
zendesk_recover_suspended_ticket - Recover suspended ticket
zendesk_delete_suspended_ticket - Delete suspended ticket

Search Operations (4 tools)

zendesk_search - Universal search across all objects
zendesk_search_tickets - Search tickets with filters
zendesk_search_users - Search users with filters
zendesk_search_organizations - Search orgs with filters

Tag Operations (2 tools)

zendesk_list_tags - List all tags in use
zendesk_autocomplete_tags - Autocomplete tag suggestions

Satisfaction Rating Operations (2 tools)

zendesk_list_satisfaction_ratings - List CSAT ratings
zendesk_get_satisfaction_rating - Get specific rating

🎨 Interactive UI Applications

The server includes 13 rich React applications for interactive data exploration:

Dashboard Applications

1. Ticket Dashboard (`ticket-dashboard`)

Interactive overview of ticket metrics and trends:

Real-time ticket count by status (new, open, pending, solved)
Priority distribution charts
Recent activity timeline
Quick stats: response time, resolution time, satisfaction score
Filter by assignee, group, or date range

2. SLA Dashboard (`sla-dashboard`)

Monitor SLA compliance and performance:

SLA policy overview with breach counts
Upcoming breaches (within 1 hour)
Policy-level compliance metrics
Historical breach trends
Filter by policy, priority, or time range

3. Satisfaction Dashboard (`satisfaction-dashboard`)

Customer satisfaction insights:

Overall CSAT score and distribution
Ratings over time (good/bad trend)
Top-rated vs lowest-rated tickets
Agent performance by satisfaction
Comment analysis and themes

Detail View Applications

4. Ticket Detail (`ticket-detail`)

Comprehensive single-ticket view:

Full ticket details with custom fields
Complete comment thread with timestamps
Assignee and requester information
Tag management interface
Status update and priority change
Related tickets and organizations

5. User Detail (`user-detail`)

Complete user profile and activity:

User profile with all custom fields
Ticket history (requested, assigned, CC'd)
Organization memberships
Email and phone identities
Role and permissions
Activity timeline

6. Organization Detail (`org-detail`)

Organization overview and management:

Organization profile with custom fields
Member list with roles
Ticket history and statistics
Domain information
Notes and tags
Associated users and groups

Grid/List Applications

7. Ticket Grid (`ticket-grid`)

Advanced ticket list with filtering:

Sortable, filterable data grid
Inline editing of status and priority
Bulk actions (assign, tag, close)
Custom column selection
Export to CSV
Saved filters and views

8. User Grid (`user-grid`)

User management interface:

Searchable user list
Filter by role, organization, status
Bulk user operations
Quick edit mode
Export user data
Role assignment

9. Organization Grid (`org-grid`)

Organization management:

Sortable organization list
Filter by domain, size, tier
Bulk operations
Member count and ticket stats
Quick actions (add user, view tickets)

Specialized Applications

10. Suspended Tickets (`suspended-tickets`)

Manage spam and suspended tickets:

List all suspended tickets with reasons
Preview ticket content
Bulk recover or delete
Spam pattern detection
Export for analysis

11. Macro Manager (`macro-manager`)

Create and manage macros:

Visual macro builder
Action preview
Test macro on sample tickets
Usage statistics
Duplicate and modify existing macros
Category organization

12. View Executor (`view-executor`)

Execute and visualize views:

Select from available views
Execute with custom parameters
Visualize results in chart/table
Export view results
Schedule view execution
Compare multiple views

13. Search Results (`search-results`)

Universal search interface:

Multi-object search (tickets, users, orgs)
Advanced filter builder
Sort and group results
Quick preview
Bulk operations on results
Save searches

Accessing UI Applications

UI apps are served via the MCP apps capability:

// Apps are automatically registered and available via MCP
// Use the MCP client's app interface to launch them

Each app is a standalone React application with:

Responsive design for desktop and mobile
Real-time data updates
Inline editing where appropriate
Export capabilities
Keyboard shortcuts
Dark mode support

📚 Usage Examples

Example 1: Create and Update a Ticket

// Create a ticket
const ticket = await zendesk_create_ticket({
  subject: "Customer needs help with API integration",
  description: "Customer is having trouble authenticating",
  priority: "high",
  requester: { email: "customer@example.com" },
  tags: ["api", "integration", "priority"]
});

// Add a comment
await zendesk_add_ticket_comment({
  ticket_id: ticket.id,
  body: "I've reviewed the logs and found the issue",
  public: true
});

// Update status
await zendesk_update_ticket({
  id: ticket.id,
  status: "solved",
  satisfaction_rating: { score: "good" }
});

Example 2: User Management Workflow

// Search for a user
const users = await zendesk_search_users({
  query: "email:john@example.com"
});

// Get user details with related data
const userDetails = await zendesk_get_user_related({
  id: users[0].id
});

// Update user's organization
await zendesk_create_organization_membership({
  user_id: users[0].id,
  organization_id: 12345
});

// Set user as an agent
await zendesk_update_user({
  id: users[0].id,
  role: "agent",
  groups: [101, 102]
});

Example 3: Automation Setup

// Create an SLA policy
const slaPolicy = await zendesk_create_sla_policy({
  title: "Premium Customer SLA",
  description: "4-hour response time for premium customers",
  filter: {
    all: [
      { field: "custom_fields.customer_tier", operator: "is", value: "premium" }
    ]
  },
  policy_metrics: [
    {
      priority: "high",
      metric: "first_reply_time",
      target: 240 // 4 hours in minutes
    }
  ]
});

// Create a trigger to auto-assign
await zendesk_create_trigger({
  title: "Auto-assign premium tickets",
  conditions: {
    all: [
      { field: "custom_fields.customer_tier", operator: "is", value: "premium" },
      { field: "status", operator: "is", value: "new" }
    ]
  },
  actions: [
    { field: "group_id", value: 101 },
    { field: "priority", value: "high" }
  ]
});

Example 4: Reporting and Analytics

// Execute a view to get filtered tickets
const highPriorityTickets = await zendesk_execute_view({
  id: "high_priority_open",
  sort_by: "created_at",
  sort_order: "desc"
});

// Get satisfaction ratings for analysis
const ratings = await zendesk_list_satisfaction_ratings({
  start_time: "2024-01-01",
  end_time: "2024-01-31"
});

// Calculate CSAT score
const goodRatings = ratings.filter(r => r.score === "good").length;
const totalRatings = ratings.length;
const csatScore = (goodRatings / totalRatings) * 100;

// Search for patterns
const escalatedTickets = await zendesk_search_tickets({
  query: "status:open priority:urgent created>2024-01-01"
});

🔧 Development

Project Structure

zendesk-mcp-server/
├── src/
│   ├── clients/
│   │   └── zendesk.ts          # API client with auth & pagination
│   ├── tools/                   # 16 tool category files
│   │   ├── tickets-tools.ts
│   │   ├── users-tools.ts
│   │   ├── organizations-tools.ts
│   │   ├── groups-tools.ts
│   │   ├── tags-tools.ts
│   │   ├── brands-tools.ts
│   │   ├── triggers-tools.ts
│   │   ├── macros-tools.ts
│   │   ├── automations-tools.ts
│   │   ├── views-tools.ts
│   │   ├── custom-fields-tools.ts
│   │   ├── sla-tools.ts
│   │   ├── satisfaction-tools.ts
│   │   ├── suspended-tickets-tools.ts
│   │   └── search-tools.ts
│   ├── ui/react-app/           # 13 React applications
│   │   ├── ticket-dashboard/
│   │   ├── sla-dashboard/
│   │   ├── ticket-detail/
│   │   ├── search-results/
│   │   ├── ticket-grid/
│   │   ├── org-detail/
│   │   ├── suspended-tickets/
│   │   ├── satisfaction-dashboard/
│   │   ├── org-grid/
│   │   ├── user-detail/
│   │   ├── macro-manager/
│   │   ├── view-executor/
│   │   └── user-grid/
│   ├── types/
│   │   └── index.ts            # TypeScript type definitions
│   ├── server.ts               # MCP server setup & registration
│   └── main.ts                 # Entry point
├── scripts/
│   └── build-apps.js           # Vite app build script
├── package.json
├── tsconfig.json
└── README.md

Building from Source

# Clone the repository
git clone https://github.com/BusyBee3333/mcpengine.git
cd mcpengine/servers/zendesk

# Install dependencies
npm install

# Type check
npm run typecheck

# Build TypeScript and React apps
npm run build

# Run in development mode
npm run dev

Running Tests

# Type checking
npm run typecheck

# Test with a real Zendesk instance
ZENDESK_SUBDOMAIN=test \
ZENDESK_EMAIL=admin@test.com \
ZENDESK_API_TOKEN=your_token \
npm start

🔒 Security

Never commit credentials: Use environment variables for all sensitive data
Use API tokens: Prefer API tokens over passwords for authentication
Restrict permissions: Create Zendesk API tokens with minimal required permissions
Rotate tokens: Regularly rotate API tokens
Monitor usage: Review API access logs in Zendesk admin

📊 Rate Limiting

The Zendesk API has rate limits:

Standard: 700 requests per minute
Enterprise: 2000 requests per minute

This server automatically:

Tracks remaining rate limit quota
Pauses requests when approaching limits
Resumes when quota resets
Provides rate limit info in errors

🐛 Troubleshooting

Authentication Errors

Error: Invalid credentials

Verify your subdomain is correct (no .zendesk.com)
Check email/API token combination
Ensure API token is enabled in Zendesk admin

Rate Limit Errors

Error: Rate limit exceeded

The server automatically handles this
For heavy usage, consider caching
Use pagination parameters to reduce request count

TypeScript Errors

Error: Cannot find module '@modelcontextprotocol/sdk'

Run npm install to install dependencies
Ensure Node.js version >= 18.0.0

🤝 Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
Make your changes with tests
Submit a pull request

📄 License

MIT License - see LICENSE file for details

🔗 Links

📞 Support

GitHub Issues: mcpengine/issues
Documentation: MCPEngine Docs

Built with ❤️ by the MCPEngine team

Making Zendesk automation accessible through the Model Context Protocol

23 KiB Raw Blame History