使用说明

Zoho Sprints MCP服务器

一个模型上下文协议（MCP）服务器，允许Claude、ChatGPT、GitHub Copilot和Cursor等AI助手管理您的 Zoho精灵通过自然语言进行项目。与其点击UI，不如告诉你的AI你需要什么——创建项目、计划冲刺、记录时间等等。

如果你觉得这有用，请⭐ 为这个仓库加星——它可以帮助其他人发现它！

特性

15工具 随着 127次操作 覆盖整个Zoho Sprints API
3个MCP提示：指导冲刺计划、项目总结和每日站立的工作流程
4 MCP资源：健康检查、配置、项目列表、团队成员
错误处理：结构化错误响应 isError AI自校正标志
响应格式：LLM友好的输出，带有分页信息和错误突出显示
多域支持：适用于所有7个Zoho数据中心(.com, .eu, .in, .com.au, .com.cn, .jp, .sa)
自动令牌刷新：每57分钟主动刷新一次+对401个响应进行被动刷新
输入验证：日期、ID、枚举、JSON数组的可重用验证器，带有清晰的错误消息
响应缓存：GET请求的内存TTL缓存（60秒）-写入时自动失效
调试模式：启用 ZOHO_SPRINTS_DEBUG=true 将所有HTTP请求/响应记录到stderr
自定义Zoho标头: X-ZA-CONVERT-RESPONSE, X-ZA-UI-VERSION, X-ZA-REQSIZE 在每次请求时发送

先决条件

Node.js 20+ 和 npm 10+ — 点击此处下载
Zoho Sprints帐户 — 注册
Zoho OAuth凭据 （客户端ID、客户端密码、刷新令牌）-- 如何获得它们

安装

npm install -g zoho-sprints-mcp

或者直接与npx一起使用：

npx zoho-sprints-mcp

快速开始

获取您的Zoho OAuth凭据 --跟随下面的指南获取您的客户端ID、客户端密码和刷新令牌
将MCP服务器添加到您的AI客户端 --复制客户端的配置(克劳德 / VS Code / 光标 / ChatGPT)并用您的凭据替换占位符值
开始与你的AI对话 --问这样的问题：
- “显示我所有的活动冲刺”
- “在Project X中创建新的bug项”
- “哪些项目逾期了？”
- “在项目#1234上记录2小时”

就是这样——不需要服务器设置，也不需要编码。当您的AI客户端启动时，MCP服务器会自动运行。

配置

环境变量

变量	必填	描述
`ZOHO_SPRINTS_REFRESH_TOKEN`	是	OAuth2刷新令牌– 如何生成
`ZOHO_SPRINTS_CLIENT_ID`	是	OAuth2客户端ID
`ZOHO_SPRINTS_CLIENT_SECRET`	是	OAuth2客户端密码
`ZOHO_SPRINTS_DOMAIN`	否	Zoho域（默认值： `com`).选项： `com`, `eu`, `in`, `com.au`, `com.cn`, `jp`, `sa`
`ZOHO_SPRINTS_ACCESS_TOKEN`	否	初始访问令牌（如果省略，则在启动时通过刷新令牌自动获取）
`ZOHO_SPRINTS_TEAM_ID`	否	工作区（团队）ID-如果只存在一个工作区，则自动检测
`ZOHO_SPRINTS_DEBUG`	否	设置为 `true` 启用stderr的详细调试日志记录
`MCP_TRANSPORT`	否	运输方式： `stdio` （默认）或 `http` 适用于ChatGPT等远程客户端
`MCP_HTTP_PORT`	否	HTTP传输端口（默认值： `3000`)
`MCP_HTTP_HOST`	否	HTTP传输的绑定地址（默认值： `0.0.0.0`)
`MCP_HTTP_PATH`	否	HTTP传输的终结点路径（默认值： `/mcp`)

正在生成OAuth2凭据

如何获取客户端ID、客户端密码和刷新令牌

关注我们 OAuth设置分步指南 创建Zoho开发人员应用程序并生成您的客户端ID、客户端密码和刷新令牌。

你也可以参考官方 Zoho OAuth自客户端概述.

所需OAuth范围

ZohoSprints.projects.ALL,ZohoSprints.sprints.ALL,ZohoSprints.items.ALL,ZohoSprints.teams.READ,ZohoSprints.timesheets.ALL,ZohoSprints.meetings.ALL,ZohoSprints.release.ALL,ZohoSprints.epic.ALL,ZohoSprints.settings.READ,ZohoSprints.teamusers.ALL

MCP客户端配置

克劳德桌面版

添加到您的 claude_desktop_config.json:

利用当地发展 （从本地版本运行）：

{
  "mcpServers": {
    "zoho-sprints": {
      "command": "node",
      "args": ["${absolute-path}/SprintsMCP/dist/index.js"],
      "env": {
        "ZOHO_SPRINTS_DOMAIN": "com",
        "ZOHO_SPRINTS_REFRESH_TOKEN": "your-refresh-token",
        "ZOHO_SPRINTS_CLIENT_ID": "your-client-id",
        "ZOHO_SPRINTS_CLIENT_SECRET": "your-client-secret",
        "ZOHO_SPRINTS_TEAM_ID": "your-team-id"
      }
    }
  }
}

替换 /absolute/path/to/SprintsMCP/dist/index.js 与您构建的实际路径 dist/index.js.一定要跑 npm run build 第一。

使用已发布的npm包:

{
  "mcpServers": {
    "zoho-sprints": {
      "command": "npx",
      "args": ["-y", "zoho-sprints-mcp"],
      "env": {
        "ZOHO_SPRINTS_DOMAIN": "com",
        "ZOHO_SPRINTS_REFRESH_TOKEN": "your-refresh-token",
        "ZOHO_SPRINTS_CLIENT_ID": "your-client-id",
        "ZOHO_SPRINTS_CLIENT_SECRET": "your-client-secret",
        "ZOHO_SPRINTS_TEAM_ID": "your-team-id"
      }
    }
  }
}

光标

添加到光标MCP设置中：

利用当地发展 （从本地版本运行）：

{
  "mcpServers": {
    "zoho-sprints": {
      "command": "node",
      "args": ["${absolute-path}/SprintsMCP/dist/index.js"],
      "env": {
        "ZOHO_SPRINTS_DOMAIN": "com",
        "ZOHO_SPRINTS_REFRESH_TOKEN": "your-refresh-token",
        "ZOHO_SPRINTS_CLIENT_ID": "your-client-id",
        "ZOHO_SPRINTS_CLIENT_SECRET": "your-client-secret",
        "ZOHO_SPRINTS_TEAM_ID": "your-team-id"
      }
    }
  }
}

替换 ${absolute-path}/SprintsMCP/dist/index.js 与您构建的实际路径 dist/index.js.一定要跑 npm run build 第一。

使用已发布的npm包:

{
  "mcpServers": {
    "zoho-sprints": {
      "command": "npx",
      "args": ["-y", "zoho-sprints-mcp"],
      "env": {
        "ZOHO_SPRINTS_DOMAIN": "com",
        "ZOHO_SPRINTS_REFRESH_TOKEN": "your-refresh-token",
        "ZOHO_SPRINTS_CLIENT_ID": "your-client-id",
        "ZOHO_SPRINTS_CLIENT_SECRET": "your-client-secret",
        "ZOHO_SPRINTS_TEAM_ID": "your-team-id"
      }
    }
  }
}

VS Code

添加到您的VS代码MCP设置(.vscode/mcp.json):

利用当地发展 （从本地版本运行）：

{
  "servers": {
    "zoho-sprints": {
      "command": "node",
      "args": ["${absolute-path}/SprintsMCP/dist/index.js"],
      "env": {
        "ZOHO_SPRINTS_DOMAIN": "com",
        "ZOHO_SPRINTS_REFRESH_TOKEN": "your-refresh-token",
        "ZOHO_SPRINTS_CLIENT_ID": "your-client-id",
        "ZOHO_SPRINTS_CLIENT_SECRET": "your-client-secret",
        "ZOHO_SPRINTS_TEAM_ID": "your-team-id"
      }
    }
  }
}

替换 ${absolute-path}/SprintsMCP/dist/index.js 与您构建的实际路径 dist/index.js.一定要跑 npm run build 第一。

使用已发布的npm包:

{
  "servers": {
    "zoho-sprints": {
      "command": "npx",
      "args": ["-y", "zoho-sprints-mcp"],
      "env": {
        "ZOHO_SPRINTS_DOMAIN": "com",
        "ZOHO_SPRINTS_REFRESH_TOKEN": "your-refresh-token",
        "ZOHO_SPRINTS_CLIENT_ID": "your-client-id",
        "ZOHO_SPRINTS_CLIENT_SECRET": "your-client-secret",
        "ZOHO_SPRINTS_TEAM_ID": "your-team-id"
      }
    }
  }
}

ChatGPT（远程/HTTP模式）

ChatGPT需要一个可公开访问的URL。部署服务器并以HTTP模式启动：

# Start in HTTP mode
MCP_TRANSPORT=http MCP_HTTP_PORT=3000 npm start

# Or use the convenience script
npm run start:http

然后在ChatGPT中→ 设置→ 开发者→ Apps → 添加MCP服务器：

Server URL: https://your-domain.com/mcp

备注：您必须部署在HTTPS后面（例如nginx、Caddy或Railway/Render/Fly.io等云平台）。服务器包含CORS标头和 /health 负载平衡器检查的端点。

可用工具

每个工具都是一个MCP工具 operation 选择动作的参数。根据需要为每个操作传递其他参数。

`manage_workspaces` （8项操作）

操作	说明
`list`	列出所有工作区
`get_settings`	获取工作区设置
`get_link_types`	获取链接类型
`get_tags`	获取自定义标签
`add_tag`	创建自定义标记
`delete_tag`	删除自定义标记
`delete_link_type`	删除链接类型
`get_global_logs`	跨项目获取日志小时数

`manage_projects` （9项操作）

操作	说明
`list`	列出项目（带筛选器）
`get_details`	获取项目详细信息
`get_backlog`	获取积压ID
`get_groups`	列出项目组
`get_priorities`	获取项目优先级
`create_group`	创建项目组
`create`	创建项目
`update`	更新项目
`delete`	删除项目

`manage_sprints` （13次操作）

操作	说明
`list`	列出冲刺（活动/即将进行/已完成/已取消）
`get_details`	获取冲刺详细信息
`create`	创建冲刺
`update`	更新sprint
`start`	开始冲刺
`complete`	完成冲刺
`cancel`	取消冲刺
`replan`	重播冲刺
`reopen`	重新开启冲刺
`delete`	删除冲刺
`get_comments`	获取sprint评论
`add_comment`	添加冲刺评论
`delete_comment`	删除sprint评论

`manage_items` （20次操作）

操作	说明
`list`	列出sprint/backlog中的项目
`get_details`	获取商品详细信息
`get_activity`	获取项目活动日志
`get_multiple`	按ID获取多个项目
`create`	创建项目
`create_subitem`	创建子项
`update`	更新项目
`move`	在冲刺之间移动项目
`delete`	删除项目
`get_comments`	获取评论
`add_comment`	添加评论
`delete_comment`	删除评论
`get_linked`	获取链接项目
`link`	链接工作项
`delink`	删除项目链接
`get_tags`	获取商品标签
`update_tags`	更新商品标签
`get_followers`	获取项目关注者
`update_followers`	添加/删除关注者
`get_timer`	获取计时器详细信息

`manage_epics` （7次操作）

操作	说明
`list`	列出史诗
`get_details`	获取史诗般的细节
`get_sprints`	获取相关冲刺
`create`	创造史诗
`associate_items`	将项目链接到史诗
`update`	更新史诗
`delete`	删除史诗

`manage_releases` （8项操作）

操作	说明
`list`	列表发布
`get_details`	获取发布详细信息
`get_stages`	获取发布阶段
`create`	创建发布
`create_stage`	创建发布阶段
`associate_items`	将项目链接到发布
`delete`	删除发布
`delete_stage`	删除发布阶段

`manage_timesheets` （4次操作）

操作	说明
`list`	获取时间日志
`add_item_log`	记录项目的小时数
`add_general`	记录一般小时数
`delete`	删除时间日志

`manage_meetings` （8项操作）

操作	说明
`list`	列出项目会议
`list_sprint`	列出冲刺会议
`get_details`	获取会议详细信息
`add`	安排会议
`delete`	删除会议
`get_comments`	获取评论
`add_comment`	添加评论
`delete_comment`	删除评论

`manage_users` （9项操作）

操作	说明
`list_workspace_user`	列出工作区用户
`list_project_user`	列出项目用户
`list_sprint_user`	列出sprint用户
`add_workspace_user`	添加工作区用户
`add_project_user`	添加项目用户
`add_sprint_user`	添加sprint用户
`delete_workspace_user`	删除工作区用户
`delete_project_user`	删除项目用户
`delete_sprint_user`	删除sprint用户

`manage_project_settings` （11项操作）

操作	说明
`get_item_types`	获取项目类型
`get_priority_types`	获取优先级类型
`get_project_status`	获取项目状态
`create_project_status`	创建状态
`update_project_status`	更新状态
`delete_project_status`	删除状态
`get_modules`	获取模块列表
`get_custom_layouts`	获取布局
`get_custom_fields`	获取自定义字段
`get_layout_fields`	获取布局字段
`get_project_custom_fields`	获取项目自定义字段

`manage_checklists` （9项操作）

操作	说明
`list_groups`	获取检查表组
`list`	获取检查表
`add_group`	创建组
`add`	添加检查表项
`change_status`	选中/取消选中
`edit`	编辑检查表项
`edit_group`	编辑组
`delete`	删除检查表项
`delete_group`	删除组

`manage_webhooks` （8项操作）

操作	说明
`get_placeholders`	获取占位符
`get_triggers`	获取触发器
`list`	列出webhooks
`get_details`	获取webhook详细信息
`create`	创建webhook
`update`	更新webhook
`delete`	删除webhook
`execute_function`	执行自定义函数

`manage_okr` （4次操作）

操作	说明
`get_statuses`	获取OKR状态
`list`	设定目标
`create`	设定一个目标
`delete`	删除目标

`manage_expenses` （8项操作）

操作	说明
`get_categories`	获取费用类别
`list`	列出费用
`get_details`	获取费用明细
`create`	创建支出
`delete`	删除费用
`get_comments`	获取评论
`add_comment`	添加评论
`delete_comment`	删除评论

`manage_custom_modules` （10次操作）

操作	说明
`list_global`	获取记录（工作区）
`list_project`	获取记录（项目）
`get_details_global`	获取记录详细信息（工作区）
`get_details_project`	获取记录详细信息（项目）
`add_global`	添加记录（工作区）
`add_project`	添加记录（项目）
`delete_global`	删除记录（工作区）
`delete_project`	删除记录（项目）
`associate`	将记录与项目关联
`get_status`	获取记录状态

MCP提示

预构建的工作流模板，指导AI客户端完成常见的多步骤操作：

提示	参数	说明
`my_overdue_workitems`	（无）	获取所有活动项目中分配给我的所有逾期工作项
`my_workitems`	（无）	获取所有活动项目中分配给我的所有工作项
`my_workitems_due_today`	（无）	获取所有活动项目中今天到期的所有工作项
`due_today_items`	（无）	获取所有活动项目（任何受让人）中今天到期的所有工作项
`project_summary`	`projectId`	综合仪表板：项目详细信息、活动冲刺、项目、团队、史诗、发布
`plan_sprint`	`projectId`, `sprintName`, `duration?`	引导式工作流程：创建sprint→ 添加待办事项→ 分配用户→ 开始
`daily_standup`	`projectId`, `sprintId`	站立报告：已完成、正在进行、待完成和潜在障碍

速率限制、重试和缓存

速率限制、指数回退的自动重试和响应缓存都是在内部处理的，不需要配置。

使用示例

服务器连接后，您可以向AI助手询问以下问题：

你说什么	会发生什么
“列出我的所有项目”	从Zoho Sprints工作区获取所有项目
“显示Project X当前冲刺中的项目”	列出活动sprint中的所有工作项
“在Project X中创建一个名为“修复登录错误”的任务”	创建新工作项
“将项目#1234移动到下一个冲刺”	在冲刺之间移动项目
“今天在项目#1234上记录3小时”	添加时间表条目
“创建一个名为“Q3发布”的史诗，并将项目链接到它”	创建史诗并关联工作项
“为项目X安排一次会议，时间为周五下午2点”	创建项目会议
“我的过期物品是什么？”	使用内置提示查找所有项目中的逾期工作
“给我一份Sprint 5的站立报告”	总结已完成、正在进行和待办事项
“给我一个项目X的项目摘要”	综合仪表板：冲刺、项目、团队、史诗、发布

调试模式

集 ZOHO_SPRINTS_DEBUG=true 启用stderr的详细日志记录。这会记录每个HTTP请求/响应的方法、URL、状态代码和持续时间，这对故障排除很有用。

许可证

麻省理工学院

使用说明

Zoho Sprints MCP服务器

特性

先决条件

安装

快速开始

配置

环境变量

正在生成OAuth2凭据

如何获取客户端ID、客户端密码和刷新令牌

所需OAuth范围

MCP客户端配置

克劳德桌面版

光标

VS Code

ChatGPT（远程/HTTP模式）

可用工具

manage_workspaces （8项操作）

manage_projects （9项操作）

manage_sprints （13次操作）

manage_items （20次操作）

manage_epics （7次操作）

manage_releases （8项操作）

manage_timesheets （4次操作）

manage_meetings （8项操作）

manage_users （9项操作）

manage_project_settings （11项操作）

manage_checklists （9项操作）

manage_webhooks （8项操作）

manage_okr （4次操作）

manage_expenses （8项操作）

manage_custom_modules （10次操作）

MCP提示

速率限制、重试和缓存

使用示例

调试模式

许可证

相关 MCP

小红书MCP服务

Figma MCP集成工具

MCP 协议测试服务器

Flomo笔记服务

GitLab项目管理服务器

Unity编辑器AI集成插件

`manage_workspaces` （8项操作）

`manage_projects` （9项操作）

`manage_sprints` （13次操作）

`manage_items` （20次操作）

`manage_epics` （7次操作）

`manage_releases` （8项操作）

`manage_timesheets` （4次操作）

`manage_meetings` （8项操作）

`manage_users` （9项操作）

`manage_project_settings` （11项操作）

`manage_checklists` （9项操作）

`manage_webhooks` （8项操作）

`manage_okr` （4次操作）

`manage_expenses` （8项操作）

`manage_custom_modules` （10次操作）