{"id":12702,"library":"zd-mcp-server","title":"Zendesk Model Context Protocol Server","description":"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.","status":"active","version":"0.5.0","language":"javascript","source_language":"en","source_url":"https://github.com/koundinya/zd-mcp-server","tags":["javascript","mcp","model-context-protocol","zendesk","ai","claude","support","tickets"],"install":[{"cmd":"npm install zd-mcp-server","lang":"bash","label":"npm"},{"cmd":"yarn add zd-mcp-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add zd-mcp-server","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { startServer } from 'zd-mcp-server';","symbol":"zd-mcp-server (global CLI)","correct":"npm install -g zd-mcp-server\nzd-mcp-server"},{"note":"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.","wrong":"const server = require('zd-mcp-server'); server.run();","symbol":"zd-mcp-server (npx execution)","correct":"npx -y zd-mcp-server"},{"note":"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.","wrong":"import { ZendeskMCPConfig } from 'zd-mcp-server';","symbol":"mcpServers (Client Configuration)","correct":"{\n  \"mcpServers\": {\n    \"zendesk\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"zd-mcp-server\"],\n      \"env\": {\n        \"ZENDESK_EMAIL\": \"your-email@company.com\",\n        \"ZENDESK_TOKEN\": \"your-zendesk-api-token\",\n        \"ZENDESK_SUBDOMAIN\": \"your-company\"\n      }\n    }\n  }\n}"}],"quickstart":{"code":"// 1. Ensure Node.js version 18 or higher is installed.\n\n// 2. Set your Zendesk API credentials as environment variables.\n//    These are crucial for the server to authenticate with Zendesk.\n//    export ZENDESK_EMAIL=\"your-email@company.com\"\n//    export ZENDESK_TOKEN=\"your-zendesk-api-token\"\n//    export ZENDESK_SUBDOMAIN=\"your-company\" // E.g., for 'your-company.zendesk.com'\n\n// 3. Launch the server directly using npx.\n//    This command starts the MCP server, making it available for AI clients\n//    to connect to. Ensure your environment variables are set in the terminal\n//    where you execute this command.\n// npx -y zd-mcp-server\n\n// Example of how to configure an AI client (e.g., Claude Desktop) to use this server.\n// This JSON snippet would be placed in your AI client's configuration file.\nconst claudeDesktopConfigExample = {\n  \"mcpServers\": {\n    \"zendesk\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"zd-mcp-server\"],\n      \"env\": {\n        \"ZENDESK_EMAIL\": process.env.ZENDESK_EMAIL ?? \"placeholder@example.com\",\n        \"ZENDESK_TOKEN\": process.env.ZENDESK_TOKEN ?? \"YOUR_ZENDESK_API_TOKEN\",\n        \"ZENDESK_SUBDOMAIN\": process.env.ZENDESK_SUBDOMAIN ?? \"your-subdomain\"\n      }\n    }\n  }\n};\n\nconsole.log(\"To run the server, execute: npx -y zd-mcp-server\");\nconsole.log(\"Alternatively, integrate it by adding the above JSON structure to your AI client's MCP configuration.\");","lang":"javascript","description":"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."},"warnings":[{"fix":"Always refer to the latest README and release notes when upgrading to new minor versions for potential migration guides or necessary adjustments.","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.5.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.5.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"command not found: zd-mcp-server"},{"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.","cause":"The environment variables `ZENDESK_EMAIL`, `ZENDESK_TOKEN`, or `ZENDESK_SUBDOMAIN` are incorrect, missing, or do not grant sufficient permissions.","error":"Zendesk API authentication failed: Invalid credentials or subdomain"},{"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.","cause":"Another process is already using the default port that `zd-mcp-server` attempts to bind to, preventing it from starting.","error":"Error: listen EADDRINUSE: address already in use :::<port_number>"}],"ecosystem":"npm"}