desk_mcp
MCP（模型上下文协议）服务器，通过3个上下文高效工具公开整个Zoho Desk API（130个类别的706个端点）。
服务器使用 搜索然后呼叫 图案：
list_categories-发现API领域search_endpoints--按关键字/类别查找正确的端点call_api--执行它operationId
先决条件
- 包子 v1.3+
- 具有API访问权限的Zoho Desk帐户
- 有效的Zoho OAuth令牌
安装
bun install配置
服务器读取三个环境变量：
| 变量 | 必填 | 默认 | 描述 |
|---|---|---|---|
ZOHO_OAUTH_TOKEN | 是 | -- | 您的Zoho OAuth令牌（请参阅 授权 在......下面 |
ZOHO_ORG_ID | 是 | - | 您的Zoho Desk组织ID。自动插入到每个API调用中。 |
ZOHO_DESK_DOMAIN | 没有 | desk.zoho.com | Zoho Desk API域。使用 desk.zoho.eu, desk.zoho.in, desk.zoho.com.au, desk.zoho.jp，或 desk.zoho.com.cn 对于其他数据中心。 |
授权
Zoho Desk API使用OAuth 2.0。要获取您的令牌：
- 注册Zoho API客户端 在 Zoho API控制台
- 选择“自客户端”进行快速测试，或选择“基于服务器的应用程序”进行生产
- 生成授权令牌 根据您的操作所需的范围（例如。，
Desk.tickets.READ,Desk.tickets.CREATE).常见范围：
- Desk.tickets.READ / CREATE / UPDATE / DELETE - Desk.contacts.READ / CREATE / UPDATE / DELETE - Desk.settings.READ / CREATE / UPDATE / DELETE - Desk.basic.READ / CREATE / UPDATE / DELETE - Desk.search.READ - Desk.articles.READ / CREATE / UPDATE / DELETE - Desk.tasks.READ / CREATE / UPDATE / DELETE
- 将授权令牌替换为访问令牌 通过：
POST https://accounts.zoho.com/oauth/v2/token
?grant_type=authorization_code
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&code=YOUR_GRANT_TOKEN- 使用返回的
access_token作为ZOHO_OAUTH_TOKEN。对于长期访问，请存储refresh_token并在到期前更换。
查找您的组织ID： 呼叫 GET https://desk.zoho.com/api/v1/organizations 用你的代币。这 id 响应中的字段是您的 ZOHO_ORG_ID.
运行服务器
bun run index.ts服务器通过以下方式进行通信 标准 使用MCP协议。
MCP集成
克劳德代码
添加到您的Claude Code MCP设置中(~/.claude/settings.json 或项目级别 .claude/settings.json):
{
"mcpServers": {
"zoho-desk": {
"command": "bun",
"args": ["/absolute/path/to/desk_mcp/index.ts"],
"env": {
"ZOHO_OAUTH_TOKEN": "your-oauth-token",
"ZOHO_ORG_ID": "your-org-id",
"ZOHO_DESK_DOMAIN": "desk.zoho.com"
}
}
}
}克劳德桌面版
添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：
{
"mcpServers": {
"zoho-desk": {
"command": "bun",
"args": ["/absolute/path/to/desk_mcp/index.ts"],
"env": {
"ZOHO_OAUTH_TOKEN": "your-oauth-token",
"ZOHO_ORG_ID": "your-org-id",
"ZOHO_DESK_DOMAIN": "desk.zoho.com"
}
}
}
}任何MCP客户端
服务器使用标准 StdioServerTransport任何兼容MCP的客户端都可以通过生成进程并通过stdin/stdout进行通信来连接。
工具
list_categories
列出所有130个Zoho Desk API类别及其端点计数。
参数： 无
示例响应：
130 categories, 706 total endpoints:
Account (14 endpoints)
Agent (18 endpoints)
Article (9 endpoints)
...
Ticket (27 endpoints)search_endpoints
按关键字和/或类别搜索端点。返回具有完整详细信息的匹配操作： operationIdHTTP方法、路径、摘要、描述、参数以及端点是否接受请求正文。
参数：
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
query | string | 否 | 搜索关键字（例如。， "create ticket", "list agents").匹配操作ID、摘要、描述、路径和标签。多个单词使用AND逻辑。 |
category | string | 否 | 按类别筛选（例如。， "Ticket", "Agent").不区分大小写 |
limit | number | 否 | 返回的最大结果数。默认值：20。 |
示例响应：
[
{
"operationId": "getTicket",
"method": "GET",
"path": "/api/v1/tickets/{ticketId}",
"category": "Ticket",
"summary": "Get a ticket",
"description": "This API fetches a ticket by its ID.",
"parameters": [
{ "name": "ticketId", "in": "path", "required": true, "description": "ID of the ticket" },
{ "name": "include", "in": "query", "required": false, "description": "..." }
],
"hasBody": false
}
]call_api
执行Zoho Desk API端点 operationId.
参数：
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
operationId | string | 是 | 操作ID来自 search_endpoints 结果。 |
params | object | 否 | 参数值。键是参数名称。路径、查询和标头参数按名称排列。对于具有请求正文的端点，请包含 body 带有JSON有效载荷的密钥。 |
示例——获取门票：
{
"operationId": "getTicket",
"params": {
"ticketId": "12345000000123"
}
}示例——创建工单：
{
"operationId": "createTicket",
"params": {
"body": {
"subject": "Printer not working",
"departmentId": "12345000000006907",
"contactId": "12345000000042032",
"description": "The office printer on floor 3 is jammed."
}
}
}示例——搜索门票：
{
"operationId": "searchTickets",
"params": {
"searchStr": "printer",
"limit": "5"
}
}典型工作流程
User: "How many open tickets are assigned to me?"
LLM calls: search_endpoints(query="list tickets assigned")
LLM calls: call_api(operationId="getAssociatedTickets", params={ "status": "open" })
LLM: "You have 12 open tickets assigned to you. Here are the most recent..."API类别
服务器对这130个类别中的706个端点进行索引：
View all categories
账户、账户附件、账户评论、账户联系人映射信息、账户重复删除、账户关注者、账户Sla、账户时间输入、活动、代理、代理距离、代理签名、代理时间输入、文章、文章附件、文章评论、文章反馈、文章翻译、自动化引擎、自动化功能账户、备份、徽章、漏洞集成、批量导入、营业时间、呼叫、呼叫评论、渠道、社区、社区附件、社区类别、社区评论、社区首选项、社区主题、社区用户、联系人、联系人附件、联系人评论、联系人重复删除、联系人关注者、联系人配置文件、联系人时间输入、合同、国家和语言，CustomView、CustomerHappiness、DashboardMetrics、Dashboards、Department、DependencyMappings、DisplayEntity、DomainMapping、EmailFailureAlert、EmailTemplates、EntityBlueprints、Event、EventComments、Field、Finance、Followers、GenericAction、Helpcenter、HelpcenterGroups、HolidayList、IMCannedMessage、IMTemplateMessage、IM_Channel、，IM_Message、IM_Metrics、IM_Session、导入、KBRootCategory、KBSection、KbCategory、KbCategoryLogo、标签、布局、布局规则标准、布局规则、许可FeaturePlan、邮件回复地址、模块、NewTicketHistory、组织、挂起审批、永久链接、固定对话、产品、产品附件、配置文件、回收站、报告集成、角色、路由参考、规则组、搜索、共享规则、技能、技能配置、技能类型、SubjectAccessRequest、SupportEmailDomain、SupportPlan、任务、任务附件、任务注释、TaskTimeEntry、TaskTimer、团队、模板文件夹、线程、工单、TicketApproval s、TicketAttachment、TicketComment、TicketCount、TicketFollowers、TicketTag、TicketTemplate、TicketTimeEntry、TicketTime、时间跟踪、上传、用户、验证规则标准、验证规则、Webhook、小部件、蓝图过渡、蓝图
测试
bun test运行70个测试，涵盖：
$ref分辨率（本地和跨文件）- OAS类型解析
- 参数解析和请求体检测
- 操作收集和重复数据删除
- 使用路径/查询/标头参数构建URL
- 工具描述生成
- 搜索和类别过滤
- 对所有155个OAS文件进行集成测试（验证所有706个端点）
项目结构
desk_mcp/
index.ts # MCP server — loads OAS specs, registers 3 tools
index.test.ts # Test suite (70 tests)
OAS/ # OpenAPI 3.1 spec files (155 JSON files)
Ticket.json
Agent.json
Contact.json
Common.json # Shared components ($ref target)
...
package.json
tsconfig.json