佐霍项目mcp

Name: 佐霍项目mcp
Author: qpiai

作者：qpiai2 星标更新：2025-10-21

安装使用来源：spider==github.com

项目介绍

Zoho Projects MCP 服务器

这是一个提供与 Zoho Projects API 集成的 Model Context Protocol (MCP) 服务器。此服务器使 AI 助手能够与 Zoho Projects 进行交互，以管理项目、任务、问题、里程碑等。

特性

支持的操作

门户管理
- 列出所有门户
- 获取门户详情
项目管理
- 列出项目
- 获取项目详情
- 创建新项目
- 更新现有项目
- 删除项目（移至回收站）
任务管理
- 列出任务（门户或项目级别）
- 获取任务详情
- 创建任务
- 更新任务
- 删除任务
问题管理
- 列出问题（门户或项目级别）
- 获取问题详情
- 创建问题
- 更新问题
阶段/里程碑管理
- 列出阶段
- 创建阶段
搜索
- 在门户或项目中搜索
- 按模块过滤（项目、任务、问题、里程碑、论坛、事件）
用户管理
- 列出门户或项目中的用户

先决条件

Node.js (v18 或更高版本)
具有 API 访问权限的 Zoho Projects 账户
Zoho OAuth 凭据

设置

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

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

前往 Zoho API 控制台
点击 “添加客户端” 按钮
选择 “自用客户端”（推荐用于个人用途）或 “基于服务器的应用程序”
填写应用程序信息：
- 客户端名称：例如，“Zoho Projects MCP”
- 主页 URL：您的网站或 http://localhost 用于测试
- 授权重定向 URI：http://localhost:8080/callback（或您首选的重定向 URI）
点击 “创建” 并记下：
- 客户端 ID（例如，1000.XXXXXXXXXX）
- 客户端密钥（请妥善保管！）

步骤 2：生成授权码

使用所需范围构建授权 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} 为您所在的区域：

US: com
EU: eu
IN: in
AU: com.au
CN: com.cn

在浏览器中打开此 URL
登录您的 Zoho 账户并授权该应用程序

您将被重定向到您的重定向 URI，并在 URL 中带有 code 参数：

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

复制 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"
}

重要提示：保存两个令牌：

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

步骤 4：查找您的门户 ID

方法 1：从 URL 查找

在浏览器中前往您的 Zoho Projects
查看 URL：https://projects.zoho.{REGION}/portal/{PORTAL_ID}/...
/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 或更高版本)

步骤：

克隆并安装：

git clone <repository-url>
cd zoho-mcp
npm install
npm run build

创建 .env 文件并填写您的凭据（参见配置部分）
运行服务器：

# 标准 I/O 服务器（适用于本地 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

区域特定的域：

US: projectsapi.zoho.com / accounts.zoho.com
EU: projectsapi.zoho.eu / accounts.zoho.eu
IN: projectsapi.zoho.in / accounts.zoho.in
AU: projectsapi.zoho.com.au / accounts.zoho.com.au
CN: 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 进行交互：

列出项目

你能列出我所有的 Zoho 项目吗？

创建新项目

创建一个名为“网站重新设计”的项目，描述为“重新设计公司网站”，开始日期为 2025-01-15，结束日期为 2025-03-31

列出任务

显示项目 ID 1234567890 的所有任务

创建任务

在项目 1234567890 中创建一个高优先级的任务，名称为“设计首页草图”，截止日期为 2025-02-15

搜索

在所有模块中搜索“错误修复”

列出问题

显示项目 1234567890 的所有问题

项目结构

zoho-projects-mcp-server/
├── src/
│   └── index.ts          # 主服务器实现
├── dist/                  # 编译后的 JavaScript（生成）
├── package.json
├── tsconfig.json
└── README.md

提供的工具

该服务器提供了以下 MCP 工具：

list_portals - 获取所有门户
get_portal - 获取门户详情
list_projects - 列出所有项目
get_project - 获取项目详情
create_project - 创建新项目
update_project - 更新项目
delete_project - 删除项目
list_tasks - 列出任务
get_task - 获取任务详情
create_task - 创建任务
update_task - 更新任务
delete_task - 删除任务
list_issues - 列出问题
get_issue - 获取问题详情
create_issue - 创建问题
update_issue - 更新问题
list_phases - 列出阶段/里程碑
create_phase - 创建阶段
search - 搜索门户或项目
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"

# 对于其他区域，请使用相应的账户域名：
# 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  # 匹配您的区域

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

API 参考

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

许可证

MIT

贡献

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

支持

对于相关问题：

MCP 服务器：在此仓库中打开一个问题
Zoho Projects API：联系 Zoho 支持或查阅其文档
Claude Desktop：查阅 Anthropic 的文档