Zoho Desk MCP Server

desk_mcp

MCP（模型上下文协议）服务器，通过3个上下文高效工具公开整个Zoho Desk API（130个类别的706个端点）。

服务器使用 搜索然后呼叫 图案：

1. list_categories -发现API领域
2. search_endpoints --按关键字/类别查找正确的端点
3. call_api --执行它 operationId

先决条件

• 包子 v1.3+
• 具有API访问权限的Zoho Desk帐户
• 有效的Zoho OAuth令牌

安装

bun install

配置

服务器读取三个环境变量：

授权

Zoho Desk API使用OAuth 2.0。要获取您的令牌：

1. 注册Zoho API客户端 在 Zoho API控制台

- 选择“自客户端”进行快速测试，或选择“基于服务器的应用程序”进行生产

1. 生成授权令牌 根据您的操作所需的范围（例如。， 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

1. 将授权令牌替换为访问令牌 通过：

   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

1. 使用返回的 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方法、路径、摘要、描述、参数以及端点是否接受请求正文。

参数：

示例响应：

[
  {
    "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": "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