Zoho Projects MCP

🚀 Zoho Projects MCP 服务器

Zoho Projects MCP 服务器是一个遵循模型上下文协议（MCP）的服务器，可与 Zoho Projects API 集成。借助该服务器，AI 助手能够与 Zoho Projects 进行交互，实现项目、任务、问题、里程碑等的管理。

✨ 主要特性

支持的操作

• 门户管理

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

• 项目管理

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

• 任务管理

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

• 问题管理

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

• 阶段/里程碑管理

  • 列出阶段
  • 创建阶段

• 搜索

  • 在门户或项目中进行搜索
  • 按模块（项目、任务、问题、里程碑、论坛、事件）进行筛选

• 用户管理

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

📦 安装指南

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

步骤 1：创建 Zoho 开发者应用

1. 访问 Zoho API 控制台
2. 点击 “添加客户端” 按钮
3. 选择 “自客户端”（个人使用推荐）或 “基于服务器的应用程序”
4. 填写应用程序详细信息：
   • 客户端名称：例如，“Zoho Projects MCP”
   • 主页 URL：您的网站或用于测试的 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
   • 澳大利亚：com.au
   • 中国：com.cn

2. 在浏览器中打开此 URL

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

4. 您将被重定向到重定向 URI，URL 中会包含一个 code 参数：

   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. 查看 URL：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

2. 使用您的凭证创建 .env 文件（请参阅下面的配置部分）

3. 运行服务器：

# 标准输入输出服务器（适用于本地 MCP 客户端）
npm start

# HTTP 服务器（适用于远程访问）
npm run start:http

3. 配置

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

# OAuth 凭证（必需）
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

# API 域名（可选，根据您所在的地区选择）
ZOHO_API_DOMAIN=https://projectsapi.zoho.com
ZOHO_ACCOUNTS_DOMAIN=https://accounts.zoho.com

# HTTP 服务器配置（可选，用于远程访问）
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
• 澳大利亚：projectsapi.zoho.com.au / accounts.zoho.com.au
• 中国：projectsapi.zoho.com.cn / accounts.zoho.com.cn

4. 配置 Claude Desktop

将以下内容添加到您的 Claude Desktop 配置文件中：

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          # 主服务器实现
├── dist/                  # 编译后的 JavaScript（自动生成）
├── 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 Desktop
• 检查 Claude Desktop 日志中的错误消息
• 验证配置中的服务器路径

OAuth 令牌管理

令牌过期

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

手动刷新令牌

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

# 对于印度地区（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"

# 对于其他地区，请使用相应的账户域名：
# 美国：https://accounts.zoho.com/oauth/v2/token
# 欧盟：https://accounts.zoho.eu/oauth/v2/token
# 澳大利亚：https://accounts.zoho.com.au/oauth/v2/token
# 中国：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  # 与您所在的地区匹配

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

API 参考

如需详细的 API 文档，请访问： https://projects.zoho.com/api-docs

📄 许可证

本项目采用 MIT 许可证。

贡献

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

支持

如果遇到以下相关问题：

• MCP 服务器：请在此仓库中提交问题
• Zoho Projects API：请联系 Zoho 支持或查看其文档
• Claude Desktop：请查看 Anthropic 的文档