jake/zendesk-mcp-2026-complete
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Customize: Platform-specific README, tools, and docs

Browse Source
This commit is contained in:
Jake Shore 2026-02-02 06:58:24 -05:00
parent 548c21a99b
commit a3609a316c
3 changed files with 105 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
.env.example
View File

@ -1,2 +1,11 @@
# Zendesk API Credentials
ZENDESK_API_KEY=your-api-key-here
# Get from: Admin Center → Apps and integrations → APIs → Zendesk API → Add API token
# Your Zendesk subdomain (e.g., "mycompany" for mycompany.zendesk.com)
ZENDESK_SUBDOMAIN=mycompany
# Your Zendesk agent email address
ZENDESK_EMAIL=agent@mycompany.com
# Your API token (not password)
ZENDESK_API_TOKEN=your-api-token-here

134
README.md
View File

@ -8,30 +8,41 @@
## 💡 What This Unlocks
**This MCP server gives AI direct access to your entire Zendesk workspace.** Instead of clicking through interfaces, you just *tell* it what you need.
**This MCP server gives AI direct access to your Zendesk customer support platform.** Instead of manually triaging tickets, assigning agents, or searching for customer issues, just *tell* AI what you need.
### 🎯 Zendesk-Native Power Moves
### 🎧 Customer Support Power Moves
The AI can directly control your Zendesk account with natural language:
The AI can manage your entire support operation with natural language:
- **Smart automation** — Complex workflows in plain English
- **Data intelligence** — Query, analyze, and export your Zendesk data
- **Rapid operations** — Bulk actions that would take hours manually
- **Cross-platform integration** — Combine Zendesk with other tools seamlessly
| Use Case | What AI Does | Tools Used |
|----------|--------------|------------|
| **"Show me all urgent tickets that have been open for more than 3 days without agent response"** | Filters tickets by priority, age, and comment history | `search_tickets`, `get_ticket` |
| **"Create ticket from customer email: subject 'Billing issue', assign to billing team, priority high"** | Creates ticket with proper routing and escalation | `create_ticket`, `list_users` |
| **"Bulk update: mark all tickets tagged 'login-bug' as solved with comment 'Fixed in v2.1'"** | Updates multiple tickets with status change and internal note | `search_tickets`, `update_ticket`, `add_comment` |
| **"Generate SLA report: tickets by status, average resolution time, agent workload distribution"** | Aggregates ticket metrics and agent activity for performance analysis | `list_tickets`, `search_tickets`, `list_users` |
| **"Find tickets from VIP customers (tag: enterprise) opened in the last 7 days, escalate any still open"** | Searches by customer segment, checks status, updates priority | `search_tickets`, `update_ticket` |
### 🔗 The Real Power: Combining Tools
### 🔗 The Real Power: Support Automation
AI can chain multiple Zendesk operations together:
AI chains Zendesk operations together:
- Query data → Filter results → Generate reports
- Search records → Update fields → Notify team
- Analyze metrics → Create tasks → Schedule follow-ups
- **Intelligent triage** → Search tickets by keywords → Classify by issue type → Auto-assign to specialists
- **Escalation workflows** → Monitor ticket age → Check priority → Update status → Notify management
- **Knowledge mining** → Analyze solved tickets → Identify common issues → Flag for documentation
## 📦 What's Inside
**102 API tools** covering the entire Zendesk platform (Support & Helpdesk).
**7 customer support tools** covering tickets, users, search, and comments:
All with proper error handling, automatic authentication, and TypeScript types.
1. **`list_tickets`** — List tickets with filters for status, priority, or date, with sorting options
2. **`get_ticket`** — Get complete ticket details including all comments, tags, and audit history
3. **`create_ticket`** — Create new tickets with subject, description, requester info, priority, and assignments
4. **`update_ticket`** — Modify ticket properties: status, priority, assignee, tags (add/remove/replace)
5. **`add_comment`** — Add public comments (visible to customer) or internal notes to tickets
6. **`list_users`** — List agents, admins, or end-users with role filtering
7. **`search_tickets`** — Advanced search with Zendesk query syntax: `status:open priority:urgent assignee:me`
All with automatic authentication, proper error handling, and TypeScript types.
## 🚀 Quick Start
@ -45,7 +56,15 @@ All with proper error handling, automatic authentication, and TypeScript types.
npm run build
```
2. **Get your Zendesk API credentials** (see Authentication section below)
2. **Get your Zendesk API credentials:**
- Log in to Zendesk
- Go to **Admin Center → Apps and integrations → APIs → Zendesk API**
- Click **Add API token**
- Copy the token and note your:
- Subdomain (e.g., `mycompany` for `mycompany.zendesk.com`)
- Agent email address
- API token
- Required permissions: Tickets (read/write), Users (read)
3. **Configure Claude Desktop:**
@ -58,9 +77,11 @@ All with proper error handling, automatic authentication, and TypeScript types.
"mcpServers": {
"zendesk": {
"command": "node",
"args": ["/ABSOLUTE/PATH/TO/zendesk-mcp/dist/index.js"],
"args": ["/ABSOLUTE/PATH/TO/zendesk-mcp-2026-complete/dist/index.js"],
"env": {
"ZENDESK_API_KEY": "your-api-key-here"
"ZENDESK_SUBDOMAIN": "mycompany",
"ZENDESK_EMAIL": "agent@mycompany.com",
"ZENDESK_API_TOKEN": "your-api-token"
}
}
}
@ -74,7 +95,7 @@ All with proper error handling, automatic authentication, and TypeScript types.
[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/zendesk-mcp)
1. Click the button above
2. Set your Zendesk API credentials in Railway dashboard
2. Set your Zendesk credentials in Railway dashboard
3. Use the Railway URL as your MCP server endpoint
### Option 3: Docker
@ -82,32 +103,52 @@ All with proper error handling, automatic authentication, and TypeScript types.
```bash
docker build -t zendesk-mcp .
docker run -p 3000:3000 \
-e ZENDESK_API_KEY=your-key \
-e ZENDESK_SUBDOMAIN=mycompany \
-e ZENDESK_EMAIL=agent@mycompany.com \
-e ZENDESK_API_TOKEN=your-token \
zendesk-mcp
```
## 🔐 Authentication
See the official [Zendesk API documentation](https://docs.zendesk.com) for authentication details.
Zendesk uses API token authentication (email/token pair):
The MCP server handles token refresh automatically.
1. **Get token**: Admin Center → Apps and integrations → APIs → Zendesk API → Add API token
2. **Format**: `email/token:api_token` (handled automatically by MCP server)
3. **Subdomain**: Your Zendesk URL subdomain (e.g., `acme` for `acme.zendesk.com`)
📚 **Official docs**: [Zendesk API Authentication](https://developer.zendesk.com/api-reference/ticketing/introduction/#security-and-authentication)
## 🎯 Example Prompts
Once connected to Claude, you can use natural language. Examples:
Once connected to Claude, use natural language:
- *"Show me recent activity in Zendesk"*
- *"Create a new record with these details..."*
- *"Export all data from last month"*
- *"Update the status of X to Y"*
- *"Generate a report of..."*
**Ticket Management:**
- *"List all open tickets sorted by priority"*
- *"Get full details on ticket #12345 including all comments"*
- *"Create a ticket: subject 'Login failure', description 'User can't access dashboard', priority urgent, assign to group ID 123"*
- *"Update ticket #6789: set status to pending, add tag 'needs-engineering'"*
**Search & Filtering:**
- *"Search for tickets with 'password reset' in subject, opened in last 7 days"*
- *"Find all tickets assigned to me with priority high or urgent"*
- *"Show tickets tagged 'billing' that are still open after 30 days"*
**User Management:**
- *"List all agents in the support team"*
- *"Find end-users with 'gmail.com' in their email"*
**Advanced Workflows:**
- *"Add internal note to ticket #4567: 'Escalated to engineering team'"*
- *"Bulk close tickets tagged 'spam' with comment 'Issue resolved'"*
- *"Generate weekly report: tickets created, solved, pending, by priority"*
## 🛠️ Development
### Prerequisites
- Node.js 18+
- npm or yarn
- Zendesk account with API access
- Zendesk account with agent access and API token
### Setup
@ -131,19 +172,32 @@ npm run test:coverage # Coverage report
## 🐛 Troubleshooting
### "Authentication failed"
- Verify your API credentials are correct
- Check that your API key hasn't been revoked
- Ensure you have the necessary permissions
### "Zendesk API error: 401 Unauthorized"
- Double-check your API token is correct
- Verify your email address matches your Zendesk agent account
- Ensure your subdomain is correct (no `.zendesk.com`, just the subdomain)
- Check that your API token hasn't been revoked in Admin Center
### "Zendesk API error: 403 Forbidden"
- Your API token may lack required permissions
- Verify your agent role has access to tickets and users
- Some operations require admin permissions (check Zendesk docs)
### "Zendesk API error: 404 Not Found"
- Ticket or user ID doesn't exist
- Check the ID is correct (use `list_tickets` or `search_tickets` to find IDs)
- Ticket may have been deleted or merged
### "Tools not appearing in Claude"
- Restart Claude Desktop after updating config
- Check that the path in `claude_desktop_config.json` is absolute
- Verify the build completed successfully (`dist/index.js` exists)
- Verify build completed: `ls dist/index.js`
- Check Claude logs: `tail -f ~/Library/Logs/Claude/mcp*.log`
## 📖 Resources
- [Zendesk API Documentation](https://docs.zendesk.com)
- [Zendesk Support API Reference](https://developer.zendesk.com/api-reference/ticketing/introduction/)
- [Zendesk Search Reference](https://support.zendesk.com/hc/en-us/articles/4408886879258-Zendesk-Support-search-reference)
- [MCP Protocol Specification](https://modelcontextprotocol.io/)
- [Claude Desktop Documentation](https://claude.ai/desktop)
@ -152,9 +206,9 @@ npm run test:coverage # Coverage report
Contributions are welcome! Please:
1. Fork the repo
2. Create a feature branch (`git checkout -b feature/amazing-tool`)
3. Commit your changes (`git commit -m 'Add amazing tool'`)
4. Push to the branch (`git push origin feature/amazing-tool`)
2. Create a feature branch (`git checkout -b feature/sla-tracking`)
3. Commit your changes (`git commit -m 'Add SLA monitoring'`)
4. Push to the branch (`git push origin feature/sla-tracking`)
5. Open a Pull Request
## 📄 License
@ -163,10 +217,10 @@ MIT License - see [LICENSE](LICENSE) for details
## 🙏 Credits
Built by [MCPEngine](https://mcpengage.com) — AI infrastructure for business software.
Built by [MCPEngage](https://mcpengage.com) — AI infrastructure for business software.
Want more MCP servers? Check out our [full catalog](https://mcpengage.com) covering 30+ business platforms.
Want more MCP servers? Check our [catalog](https://mcpengine.pages.dev) covering 30+ business platforms.
---
**Questions?** Open an issue or join our [Discord community](https://discord.gg/mcpengine).
**Questions?** Open an issue or join our [Discord community](https://discord.gg/mcpengage).

2
package.json
View File

@ -4,7 +4,7 @@
"description": "MCP server for Zendesk API - 2026 Complete Version",
"type": "module",
"main": "dist/index.js",
"author": "MCPEngine <hello@mcpengage.com>",
"author": "MCPEngage <hello@mcpengage.com>",
"license": "MIT",
"repository": {
"type": "git",