Zendesk Model Context Protocol Server

0.5.0 · active · verified Sun Apr 19

The `zd-mcp-server` package provides a Model Context Protocol (MCP) server designed to integrate AI assistants, such as Claude or Cursor, with Zendesk Support. It enables conversational AI to interact with Zendesk tickets, facilitating operations like creating, reading, updating, and searching tickets, adding public comments or private internal notes, and managing ticket tags. The current stable version is 0.5.0, indicating a pre-1.0 development stage, likely with an agile release cadence focused on feature development and stability improvements. Its key differentiator is providing a standardized MCP interface to Zendesk, abstracting the Zendesk API complexities for AI agents, and simplifying setup for popular AI clients. It leverages Zendesk API tokens for secure access.

Common errors

```
command not found: zd-mcp-server
```
cause The `zd-mcp-server` command is not available in your system's PATH, either because it was not installed globally or `npx` is not functioning correctly.

fix Install the package globally with `npm install -g zd-mcp-server`, or use `npx -y zd-mcp-server` to run it without a global installation. Verify that Node.js and npm/npx are correctly installed and configured in your PATH.
```
Zendesk API authentication failed: Invalid credentials or subdomain
```
cause The environment variables `ZENDESK_EMAIL`, `ZENDESK_TOKEN`, or `ZENDESK_SUBDOMAIN` are incorrect, missing, or do not grant sufficient permissions.

fix Double-check your `export` commands or client configuration for typos. Ensure the Zendesk API token is active and associated with the correct email and subdomain. Verify the token has the necessary permissions to access Zendesk tickets.
```
Error: listen EADDRINUSE: address already in use :::<port_number>
```
cause Another process is already using the default port that `zd-mcp-server` attempts to bind to, preventing it from starting.

fix Identify and stop the process using the conflicting port (e.g., `lsof -i :<port_number>`). If `zd-mcp-server` supports a port configuration (not explicitly mentioned but common for servers), configure it to use an alternative available port.

Warnings

breaking The package is currently at version 0.5.0, indicating it is in a pre-1.0 development phase. Breaking changes to the CLI arguments, environment variables, or MCP protocol implementation may occur in minor versions.
Fix: Always refer to the latest README and release notes when upgrading to new minor versions for potential migration guides or necessary adjustments.
gotcha Zendesk API tokens, email, and subdomain are highly sensitive credentials. Exposing them can lead to unauthorized access to your Zendesk account. Environment variables should be managed securely and never committed to source control.
Fix: Use a secure secrets management solution (e.g., environment variables, a vault service) for production deployments. Always follow the principle of least privilege for API tokens.
gotcha The server requires Node.js version 18 or higher to run. Running with older Node.js versions may result in runtime errors or unexpected behavior.
Fix: Ensure your environment uses Node.js v18.0.0 or newer. Use a version manager like `nvm` (Node Version Manager) to easily switch or install required Node.js versions.

Install

npm install zd-mcp-server npm
yarn add zd-mcp-server yarn
pnpm add zd-mcp-server pnpm

Imports

zd-mcp-server (global CLI)
wrong:
```
import { startServer } from 'zd-mcp-server';
```
correct:
```
npm install -g zd-mcp-server
zd-mcp-server
```
This package is a command-line interface tool and server, not a JavaScript library. It's intended to be run as a standalone process after global installation.
zd-mcp-server (npx execution)
wrong:
```
const server = require('zd-mcp-server'); server.run();
```
correct:
```
npx -y zd-mcp-server
```
Using `npx` is the recommended way for quick starts or temporary execution without a global npm installation. It ensures the latest version is used and avoids polluting global node_modules.

mcpServers (Client Configuration)

wrong:

import { ZendeskMCPConfig } from 'zd-mcp-server';

correct:

{
  "mcpServers": {
    "zendesk": {
      "command": "npx",
      "args": ["-y", "zd-mcp-server"],
      "env": {
        "ZENDESK_EMAIL": "your-email@company.com",
        "ZENDESK_TOKEN": "your-zendesk-api-token",
        "ZENDESK_SUBDOMAIN": "your-company"
      }
    }
  }
}

For integration with AI clients (e.g., Claude Desktop, Cursor IDE), the server is typically launched by the client via a JSON configuration file. The 'env' block passes necessary credentials to the launched process.

Quickstart

Demonstrates how to quickly set up and run the `zd-mcp-server` using `npx`, including essential environment variable configuration and an example of client-side integration JSON.

// 1. Ensure Node.js version 18 or higher is installed.

// 2. Set your Zendesk API credentials as environment variables.
//    These are crucial for the server to authenticate with Zendesk.
//    export ZENDESK_EMAIL="your-email@company.com"
//    export ZENDESK_TOKEN="your-zendesk-api-token"
//    export ZENDESK_SUBDOMAIN="your-company" // E.g., for 'your-company.zendesk.com'

// 3. Launch the server directly using npx.
//    This command starts the MCP server, making it available for AI clients
//    to connect to. Ensure your environment variables are set in the terminal
//    where you execute this command.
// npx -y zd-mcp-server

// Example of how to configure an AI client (e.g., Claude Desktop) to use this server.
// This JSON snippet would be placed in your AI client's configuration file.
const claudeDesktopConfigExample = {
  "mcpServers": {
    "zendesk": {
      "command": "npx",
      "args": ["-y", "zd-mcp-server"],
      "env": {
        "ZENDESK_EMAIL": process.env.ZENDESK_EMAIL ?? "placeholder@example.com",
        "ZENDESK_TOKEN": process.env.ZENDESK_TOKEN ?? "YOUR_ZENDESK_API_TOKEN",
        "ZENDESK_SUBDOMAIN": process.env.ZENDESK_SUBDOMAIN ?? "your-subdomain"
      }
    }
  }
};

console.log("To run the server, execute: npx -y zd-mcp-server");
console.log("Alternatively, integrate it by adding the above JSON structure to your AI client's MCP configuration.");

view raw JSON →