Zendesk MCP Server

A Model Context Protocol (MCP) server that provides AI assistants like Claude with seamless integration to Zendesk Support. Enables natural language interactions with Zendesk tickets, allowing you to search, create, update, and manage support tickets through conversational AI.

✨ Features

🎫 Complete Ticket Management: Create, read, update, and search Zendesk tickets
💬 Comments & Notes: Add public comments and private internal notes
🔍 Advanced Search: Search tickets using Zendesk's powerful query syntax
🔗 Incident Management: Retrieve and manage linked incident tickets
🏷️ Tag Management: Add and manage ticket tags and metadata
🔒 Secure Authentication: Uses Zendesk API tokens for secure access
🚀 Easy Installation: Available via npm, npx, or manual setup

🚀 Quick Start

Option 1: NPM Installation (Recommended)

npm install -g zd-mcp-server

Option 2: Use with npx (No Installation)

npx zd-mcp-server

Tool Filtering

You can filter which tools are available using the --enabled-tools flag with a regex pattern:

# Enable only search-related tools
zd-mcp-server --enabled-tools="search"

# Enable ticket and search tools
zd-mcp-server --enabled-tools="ticket|search"  

# Enable only read operations (get/search tools)
zd-mcp-server --enabled-tools="get|search"

# See all available options
zd-mcp-server --help

HTTP Transport

The server supports both stdio (default) and HTTP transports:

# Run over stdio (default)
zd-mcp-server

# Run over HTTP on port 3000
zd-mcp-server --http

# Run over HTTP on custom port
zd-mcp-server --http 8080

# Combine with tool filtering
zd-mcp-server --http 3000 --enabled-tools="search|get"

When running in HTTP mode, the server provides:

MCP endpoint: http://localhost:3000/mcp
OAuth discovery: http://localhost:3000/.well-known/oauth-authorization-server
Client registration: http://localhost:3000/register
Authorization: http://localhost:3000/authorize
Token exchange: http://localhost:3000/token

Option 3: Development Setup

git clone https://github.com/koundinya/zd-mcp-server.git
cd zd-mcp-server
npm install
npm run build

⚙️ Configuration

Environment Variables

Set these environment variables in your system or MCP client configuration:

export ZENDESK_EMAIL="your-email@company.com"
export ZENDESK_TOKEN="your-zendesk-api-token"
export ZENDESK_SUBDOMAIN="your-company"  # from https://your-company.zendesk.com

Claude Desktop Setup

Add to your Claude Desktop configuration file:

Location:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

Configuration:

{
  "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"
      }
    }
  }
}

With Tool Filtering:

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

Alternative (if installed globally):

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

Cursor IDE Setup

Add to ~/.cursor/mcp.json or .cursor/mcp.json in your project:

{
  "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"
      }
    }
  }
}

Other MCP Clients

For other MCP-compatible clients (Cline, Windsurf, etc.), refer to their documentation for MCP server configuration. The server supports standard MCP protocols.

🛠️ Available Tools

Tool	Description	Example Usage
`zendesk_oauth_login`	Login using OAuth device flow	"Login to Zendesk"
`zendesk_oauth_logout`	Logout from OAuth session	"Logout from Zendesk"
`zendesk_get_ticket`	Retrieve a ticket by ID	"Get ticket #12345"
`zendesk_get_ticket_details`	Get detailed ticket with comments	"Show me full details for ticket #67890"
`zendesk_search`	Search tickets and resources with advanced filtering, sorting, and pagination	"Find all urgent tickets from last week, sorted by created date"
`zendesk_create_ticket`	Create a new ticket	"Create a high priority ticket for login issues"
`zendesk_update_ticket`	Update ticket properties	"Set ticket #555 to solved status"
`zendesk_add_private_note`	Add internal agent notes	"Add a private note about investigation progress"
`zendesk_add_public_note`	Add public customer comments	"Reply to customer with solution steps"
`zendesk_get_linked_incidents`	Get incident tickets linked to problems	"Show incidents related to this problem ticket"

💬 Usage Examples

Once configured, you can use natural language with your AI assistant:

OAuth Authentication

"Login to Zendesk"
"Logout from Zendesk"

Ticket Management

"Show me all high priority tickets assigned to me"
"Create a new ticket: Customer can't access dashboard, priority urgent"
"Update ticket #12345 status to pending and add a note about waiting for customer response"

Search & Discovery

"Find all solved tickets from this week tagged with 'billing'"
"Search for open tickets containing 'password reset'"
"Show me tickets created by john@company.com in the last 30 days"
"Search for urgent tickets, show 25 per page, sorted by creation date descending"
"Find all users in the organization, paginate to page 3"
"Search for tickets with status open, sorted by priority ascending"

Customer Communication

"Add a public comment to ticket #789: 'We've identified the issue and working on a fix'"
"Add a private note: 'Customer confirmed the workaround is effective'"

Advanced Queries

"Find all problem tickets that have linked incidents"
"Show me escalated tickets that haven't been updated in 2 days"
"Get details for ticket #456 including all comments and history"

🔑 Authentication Setup

The server supports two authentication methods:

Option 1: OAuth Flow (Recommended)

Create OAuth App in Zendesk:
- Go to Admin Center → Apps and integrations → APIs → OAuth Clients
- Click Add OAuth client
- Set Client Name: "MCP Server Integration"
- Set Redirect URLs: urn:ietf:wg:oauth:2.0:oob (for device flow)
- Copy the Client ID and Client Secret

Configure Environment Variables:

export ZENDESK_CLIENT_ID="your-oauth-client-id"
export ZENDESK_CLIENT_SECRET="your-oauth-client-secret"
export ZENDESK_SUBDOMAIN="your-company"

Login Process:
- Use the zendesk_oauth_login tool to initiate device flow
- Follow the provided URL and enter the code
- Once authenticated, all API calls will use OAuth tokens

Option 2: API Token (Legacy)

Generate API Token:
- Log in to your Zendesk account
- Go to Admin Center → Apps and integrations → APIs → Zendesk API
- Click Add API token
- Add description: "MCP Server Integration"
- Click Create and copy the token

Configure Environment Variables:

export ZENDESK_EMAIL="your-email@company.com"
export ZENDESK_TOKEN="your-zendesk-api-token"
export ZENDESK_SUBDOMAIN="your-company"

Subdomain Setup

Your Zendesk URL format: https://YOUR-SUBDOMAIN.zendesk.com Use YOUR-SUBDOMAIN as the ZENDESK_SUBDOMAIN value.

Required Permissions

Ensure your Zendesk user account has:

Agent role (minimum)
Ticket access permissions
API access enabled

🔧 Development

Project Structure

zd-mcp-server/
├── src/
│   ├── index.ts          # Server entry point
│   └── tools/
│       └── index.ts      # Zendesk tool implementations
├── dist/                 # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

Building from Source

git clone https://github.com/koundinya/zd-mcp-server.git
cd zd-mcp-server
npm install
npm run build

Running Locally

# Start the server
npm start

# Development mode with auto-rebuild
npm run dev

Testing

# Test with MCP Inspector (if available)
npx @modelcontextprotocol/inspector zd-mcp-server

# Or test the built version
npx @modelcontextprotocol/inspector node dist/index.js

🔍 Troubleshooting

Common Issues

❌ "Authentication failed" errors

Verify your API token is correct and hasn't expired
Ensure your email address matches your Zendesk account
Check that your subdomain is spelled correctly (no .zendesk.com suffix)

❌ "Permission denied" errors

Verify your Zendesk user has Agent permissions or higher
Ensure API access is enabled for your account
Check if your token has the required scopes

❌ "Server not found" errors

Ensure you've installed the package: npm install -g zd-mcp-server
Try using npx instead: npx zd-mcp-server
Check that your MCP client configuration file syntax is correct

❌ "Environment variables not set" errors

Verify all three environment variables are set: ZENDESK_EMAIL, ZENDESK_TOKEN, ZENDESK_SUBDOMAIN
Restart your MCP client after setting environment variables
Check for typos in environment variable names

Debug Mode

Enable debug logging:

DEBUG=zd-mcp-server:* zd-mcp-server

Log Files

Check MCP client logs:

Claude Desktop: ~/Library/Logs/Claude/ (macOS) or %APPDATA%/Claude/logs/ (Windows)
Cursor: Check the output panel for MCP server logs
Terminal: Run server directly to see real-time logs

📚 Advanced Usage

Search Query Syntax

Zendesk search supports powerful query operators:

# Status-based searches
status:open status:pending status:solved

# Priority searches  
priority:urgent priority:high priority:normal priority:low

# Date-based searches
created>2024-01-01 updated<2024-01-31

# Tag searches
tags:billing tags:technical-issue

# Requester searches
requester:customer@company.com

# Resource type filtering
type:ticket type:user type:organization type:group

# Complex combinations
status:open priority:high created>2024-01-01 tags:billing

Enhanced Search Parameters

The search tool now supports advanced filtering and pagination options:

# Pagination
per_page: 1-100 results per page (default: 100)
page: Page number for pagination (starts from 1)

# Sorting
sort_by: Field to sort by (created_at, updated_at, priority, status, ticket_type, etc.)
sort_order: asc (ascending) or desc (descending)

# Resource type filtering
type: ticket, user, organization, or group

# Example usage
"Search for open tickets, 25 per page, page 2, sorted by priority descending"
"Find all users, sorted by creation date, show first 50 results"
"Search urgent tickets from last month, sorted by update date"

Batch Operations

While the server doesn't directly support batch operations, you can chain commands:

"Search for all urgent tickets, then show me details for the first 3 results"
"Find tickets tagged 'billing', update them to normal priority, and add a note about the billing system maintenance"

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Reporting Issues

Found a bug? Please open an issue with:

Description of the problem
Steps to reproduce
Expected behavior
Your environment (OS, Node.js version, MCP client)
Relevant log outputs

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

GitHub: https://github.com/koundinya/zd-mcp-server
npm: https://www.npmjs.com/package/zd-mcp-server
Zendesk API Docs: https://developer.zendesk.com/api-reference/
Model Context Protocol: https://modelcontextprotocol.io/

🆘 Support

Issues: GitHub Issues
Zendesk API: Zendesk Developer Documentation
MCP Protocol: MCP Documentation

Made with ❤️ for the MCP and Zendesk communities

Name		Name	Last commit message	Last commit date
Latest commit History 15 Commits
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
STREAMABLE_HTTP.md		STREAMABLE_HTTP.md
package.json		package.json
tsconfig.json		tsconfig.json

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Zendesk MCP Server

✨ Features

🚀 Quick Start

Option 1: NPM Installation (Recommended)

Option 2: Use with npx (No Installation)

Tool Filtering

HTTP Transport

Option 3: Development Setup

⚙️ Configuration

Environment Variables

Claude Desktop Setup

Cursor IDE Setup

Other MCP Clients

🛠️ Available Tools

💬 Usage Examples

OAuth Authentication

Ticket Management

Search & Discovery

Customer Communication

Advanced Queries

🔑 Authentication Setup

Option 1: OAuth Flow (Recommended)

Option 2: API Token (Legacy)

Subdomain Setup

Required Permissions

🔧 Development

Project Structure

Building from Source

Running Locally

Testing

🔍 Troubleshooting

Common Issues

Debug Mode

Log Files

📚 Advanced Usage

Search Query Syntax

Enhanced Search Parameters

Batch Operations

🤝 Contributing

Development Setup

Reporting Issues

📄 License

🔗 Links

🆘 Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages