Zoho Sprints MCP

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

快速开始

1. 获取您的Zoho OAuth凭据 --跟随 下面的指南 获取您的客户端ID、客户端密码和刷新令牌
2. 将MCP服务器添加到您的AI客户端 --复制客户端的配置(克劳德 / VS Code / 光标 / ChatGPT)并用您的凭据替换占位符值
3. 开始与你的AI对话 --问这样的问题：

- *“显示我所有的活动冲刺”* - *“在Project X中创建新的bug项”* - *“哪些项目逾期了？”* - *“在项目#1234上记录2小时”*

就是这样——不需要服务器设置，也不需要编码。当您的AI客户端启动时，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项操作）

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提示

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

速率限制、重试和缓存

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

使用示例

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

调试模式

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

许可证

麻省理工学院