AI导哈

Zoho项目管理集成服务

一个提供与Zoho Projects API集成的模型上下文协议（MCP）服务器，使AI助手能够管理项目、任务、问题、里程碑等。

  • by qpiai
  • JavaScript
  • 本地部署
  • 8 星标
  • 更新于
在 GitHub 查看 qpiai/zoho-projects-mcp

使用说明

Zoho Projects MCP 服务器

一个提供与Zoho Projects API集成的模型上下文协议（MCP）服务器。此服务器使AI助手能够与Zoho Projects进行交互，以管理项目、任务、问题、里程碑等。

特点

支持的操作

  • 门户管理

    • 列出所有门户
    • 获取门户详情

  • 项目管理

    • 列出项目
    • 获取项目详情
    • 创建新项目
    • 更新现有项目
    • 删除项目（移至回收站）

  • 任务管理

    • 列出任务（门户级别或项目级别）
    • 获取任务详情
    • 创建任务
    • 更新任务
    • 删除任务

  • 问题管理

    • 列出问题（门户或项目层面）
    • 获取问题详情
    • 创建问题
    • 更新问题

  • 阶段/里程碑管理

    • 列出阶段
    • 创建阶段

  • 搜索

    • 在门户或项目中进行搜索
    • 按模块过滤（项目、任务、问题、里程碑、论坛、活动）

  • 用户管理

    • 列出门户或项目中的用户

先决条件

  1. Node.js (v18 或更高版本)
  2. Zoho Projects 账户 通过API访问
  3. Zoho OAuth 凭据

设置

1. 获取Zoho OAuth凭据（详细指南）

步骤1：创建一个Zoho开发者应用程序

  1. 首选 Zoho API控制台
  2. 点击 “Add Client”翻译成中文是“添加客户端” 按钮
  3. 选择 “Self Client”可以翻译为“自助客户端”或“自我客户端”，具体取决于上下文和使用场景。在这里，我选择了“自助客户端”作为翻译，因为它更常用于描述一种用户可以自行操作的软件或系统界面 （建议个人使用）或 “基于服务器的应用程序”
  4. 填写申请详情：
    • 客户名称例如，“Zoho Projects MCP”
    • 主页网址您的网站或 http://localhost 用于测试
    • 授权重定向URI： http://localhost:8080/callback （或您偏好的重定向URL）
  5. 点击 “创造” 并记下：
    • 客户端ID （例如。， 1000.XXXXXXXXXX）
    • 客户端密钥 （请保持此信息的安全！）

步骤2：生成授权码

  1. 构建包含所需作用域的授权URL：

    https://accounts.zoho.{REGION}/oauth/v2/auth?
  scope=ZohoProjects.portals.ALL,ZohoProjects.projects.ALL,ZohoProjects.tasks.ALL,ZohoProjects.bugs.ALL,ZohoProjects.milestones.ALL,ZohoProjects.users.READ,ZohoSearch.securesearch.READ
  &client_id=YOUR_CLIENT_ID
  &response_type=code
  &access_type=offline
  &redirect_uri=YOUR_REDIRECT_URI

    替换 {REGION} 与您的地区：

    • 美国： com
    • 欧盟： eu
    • 在……里面 in
    • AU：（此处“AU”可能是一个缩写或特定语境下的术语，没有具体上下文难以给出准确翻译，但一般可理解为“澳大利亚”或根据具体语境翻译为其他含义） com.au
    • CN:（此处“CN”通常代表“中国”的英文缩写，但在此上下文中可能仅作为一个标识或代码使用，因此直接翻译为“中国”或保留原样“CN”均可，具体取决于上下文需求。若需更具体的翻译，请提供更多上下文信息。） com.cn

  2. 在您的浏览器中打开此URL

  3. 登录您的Zoho账户并授权该应用程序

  4. 您将被重定向到您的重定向URI，并附带一个 代码 URL中的参数：

    http://localhost:8080/callback?code=1000.XXXXX.XXXXX&location=in&accounts-server=https://accounts.zoho.in

  5. 复制 code 值（有效期约2分钟，请立即使用！）

步骤3：用代码兑换代币

使用此curl命令来获取您的访问令牌和刷新令牌：

curl -X POST https://accounts.zoho.{REGION}/oauth/v2/token \
  -d "code=YOUR_AUTHORIZATION_CODE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=YOUR_REDIRECT_URI" \
  -d "grant_type=authorization_code"

响应将包含：

{
  "access_token": "1000.xxxx.yyyy",
  "refresh_token": "1000.zzzz.aaaa",
  "expires_in": 3600,
  "api_domain": "https://www.zohoapis.in",
  "token_type": "Bearer"
}

重要： 保存这两个令牌：

  • 访问令牌有效期1小时（由服务器自动刷新）
  • 刷新令牌长期有效，用于获取新的访问令牌

步骤4：查找您的门户ID

方法1：从URL

  1. 在浏览器中访问您的Zoho Projects
  2. 看看这个网址： https://projects.zoho.{REGION}/portal/{PORTAL_ID}/...
  3. 后面的数字 /portal/ 是您的门户ID（例如。， 60028147039）

方法2：使用API

curl -X GET https://projectsapi.zoho.{REGION}/api/v3/portals \
  -H "Authorization: Zoho-oauthtoken YOUR_ACCESS_TOKEN"

响应将列出所有您的门户及其ID。

步骤5：验证凭据

使用此API调用测试您的设置：

curl -X GET https://projectsapi.zoho.{REGION}/api/v3/portal/YOUR_PORTAL_ID/projects \
  -H "Authorization: Zoho-oauthtoken YOUR_ACCESS_TOKEN"

预期： 包含您项目列表的JSON响应 如果出错： 检查令牌、门户ID和API域是否与您的区域匹配

所需范围概要

确保您的OAuth令牌包含以下范围：

  • ✅ ZohoProjects.portals.ALL - 门户操作
  • ✅ ZohoProjects.projects.ALL - 项目管理
  • ✅ ZohoProjects.tasks.ALL - 任务管理
  • ✅ 翻译为中文是：✅（这个符号本身在中文中没有直接对应的翻译，它通常用于表示“正确”、“已确认”或“已完成”的意思，所以在这里可以保留原样或根据上下文翻译为“正确”、“已确认”等）。如果仅就符号本身而言，中文中没有直接对应的翻译，但其含义可以根据上下文来理解。 ZohoProjects.bugs.ALL - 问题/缺陷管理
  • ✅ ZohoProjects.milestones.ALL - 里程碑/阶段管理
  • ✅ ZohoProjects.users.READ - 用户信息
  • ✅ ZohoSearch.securesearch.READ - 搜索功能

2. 设置与安装

Node.js 安装设置

先决条件：

  • Node.js（v18或更高版本）

步骤：

  1. 克隆并安装：
git clone <repository-url>
cd zoho-mcp
npm install
npm run build

  1. 创建 .env 附上您的凭证文件（见下文“配置”部分）

  2. 启动服务器：

# Stdio server (for local MCP clients)
npm start

# HTTP server (for remote access)
npm run start:http

3. 配置

创建一个 .env 在项目根目录中创建一个文件，包含以下变量：

# OAuth credentials (required)
ZOHO_ACCESS_TOKEN=your_access_token_here
ZOHO_REFRESH_TOKEN=your_refresh_token_here
ZOHO_CLIENT_ID=your_client_id_here
ZOHO_CLIENT_SECRET=your_client_secret_here

# Portal configuration (required)
ZOHO_PORTAL_ID=your_portal_id_here

# API domain (optional, choose based on your region)
ZOHO_API_DOMAIN=https://projectsapi.zoho.com
ZOHO_ACCOUNTS_DOMAIN=https://accounts.zoho.com

# HTTP Server configuration (optional, for remote access)
HTTP_PORT=3001
ALLOWED_ORIGINS=http://localhost:3000
ALLOWED_HOSTS=127.0.0.1,localhost

区域特定领域：

  • 美国： projectsapi.zoho.com / accounts.zoho.com
  • 欧盟： projectsapi.zoho.eu / accounts.zoho.eu
  • 在……里面 projectsapi.zoho.in / accounts.zoho.in
  • AU： projectsapi.zoho.com.au / accounts.zoho.com.au
  • CN：（此处“CN”通常代表“中国”或“中国网络”的缩写，但具体含义需根据上下文确定，若直接作为缩写使用，则可译为“中国”或保持原样） projectsapi.zoho.com.cn / accounts.zoho.com.cn

4. 配置Claude桌面版

在您的Claude桌面配置文件中添加：

macOS（发音类似“麦克斯”）： ~/Library/Application Support/Claude/claude_desktop_config.json Windows： %APPDATA%\Claude\claude_desktop_config.json

对于Node.js的设置：

{
  "mcpServers": {
    "zoho-projects": {
      "command": "node",
      "args": ["/absolute/path/to/zoho-mcp/dist/index.js"],
      "env": {
        "ZOHO_ACCESS_TOKEN": "your_access_token_here",
        "ZOHO_REFRESH_TOKEN": "your_refresh_token_here",
        "ZOHO_CLIENT_ID": "your_client_id_here",
        "ZOHO_CLIENT_SECRET": "your_client_secret_here",
        "ZOHO_PORTAL_ID": "your_portal_id_here",
        "ZOHO_API_DOMAIN": "https://projectsapi.zoho.in",
        "ZOHO_ACCOUNTS_DOMAIN": "https://accounts.zoho.in"
      }
    }
  }
}

使用示例

一旦配置完成，您就可以使用Claude与Zoho Projects进行交互：

列出项目

Can you list all my Zoho Projects?

创建一个新项目

Create a new project called "Website Redesign" with description "Redesign company website" starting on 2025-01-15 and ending on 2025-03-31

列出任务

Show me all tasks in project ID 1234567890

创建任务

Create a high priority task called "Design homepage mockup" in project 1234567890, due on 2025-02-15

搜索

Search for "bug fix" in all modules

列出问题

Show me all issues in project 1234567890

项目结构

zoho-projects-mcp-server/
├── src/
│   └── index.ts          # Main server implementation
├── dist/                  # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
└── README.md

可用工具

服务器提供以下MCP工具：

  1. list_portals - 获取所有门户
  2. get_portal - 获取门户详情
  3. list_projects - 列出所有项目
  4. get_project - 获取项目详情
  5. create_project - 创建一个新项目
  6. update_project - 更新一个项目
  7. delete_project - 删除一个项目
  8. list_tasks - 列出任务
  9. get_task - 获取任务详情
  10. create_task - 创建一个任务
  11. update_task - 更新任务
  12. delete_task - 删除任务
  13. list_issues - 列出问题
  14. get_issue - 获取问题详情
  15. create_issue - 创建一个问题
  16. update_issue - 更新一个问题
  17. list_phases - 列出阶段/里程碑
  18. create_phase - 创建一个阶段
  19. search - 搜索门户或项目
  20. list_users - 列出用户

故障排除

认证问题

  • 确保您的访问令牌有效且未过期
  • 验证令牌是否具有所需的范围
  • 检查门户网站ID是否正确

API错误

  • 请查阅Zoho API文档以了解速率限制
  • 确保您为所在地区使用了正确的API域
  • 验证用户是否具有适当的权限

连接问题

  • 配置更改后重启Claude桌面版
  • 检查Claude桌面日志中的错误信息
  • 验证配置中的服务器路径

OAuth令牌管理

令牌过期

访问令牌在1小时（3600秒）后过期。此MCP服务器会自动使用刷新令牌来更新令牌。

手动刷新令牌

如果您需要手动刷新您的访问令牌：

# For India region (accounts.zoho.in)
curl -X POST https://accounts.zoho.in/oauth/v2/token \
  -d "refresh_token=YOUR_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "grant_type=refresh_token"

# For other regions, use the appropriate accounts domain:
# US: https://accounts.zoho.com/oauth/v2/token
# EU: https://accounts.zoho.eu/oauth/v2/token
# AU: https://accounts.zoho.com.au/oauth/v2/token
# CN: https://accounts.zoho.com.cn/oauth/v2/token

响应示例：

{
  "access_token": "1000.xxx.yyy",
  "scope": "ZohoProjects.portals.ALL ZohoProjects.projects.ALL...",
  "api_domain": "https://www.zohoapis.in",
  "token_type": "Bearer",
  "expires_in": 3600
}

自动令牌刷新

MCP服务器会自动处理令牌刷新。请配置以下环境变量：

ZOHO_REFRESH_TOKEN=your_refresh_token_here
ZOHO_CLIENT_ID=your_client_id_here
ZOHO_CLIENT_SECRET=your_client_secret_here
ZOHO_ACCOUNTS_DOMAIN=https://accounts.zoho.in  # Match your region

服务器将在访问令牌过期前自动刷新它。

API 参考

如需详细的API文档，请访问： https://projects.zoho.com/api-docs 的中文翻译是：“Zoho Projects API 文档”

许可证

麻省理工学院（MIT）

做出贡献

欢迎贡献！请随时提交问题或拉取请求。

支持

对于以下相关问题：

  • MCP服务器在这个仓库中打开一个问题（或议题）
  • Zoho Projects API联系Zoho支持团队或查阅其文档
  • **Claude Desktop（中文可译为“Claude桌面版”）**查阅Anthropic的文档

相关 MCP