Zoho Projects MCP 服务器
一个提供与Zoho Projects API集成的模型上下文协议（MCP）服务器。此服务器使AI助手能够与Zoho Projects进行交互，以管理项目、任务、问题、里程碑等。
特点
支持的操作
- 门户管理
- 列出所有门户 - 获取门户详情
- 项目管理
- 列出项目 - 获取项目详情 - 创建新项目 - 更新现有项目 - 删除项目（移至回收站）
- 任务管理
- 列出任务（门户级别或项目级别） - 获取任务详情 - 创建任务 - 更新任务 - 删除任务
- 问题管理
- 列出问题（门户或项目层面） - 获取问题详情 - 创建问题 - 更新问题
- 阶段/里程碑管理
- 列出阶段 - 创建阶段
- 搜索
- 在门户或项目中进行搜索 - 按模块过滤（项目、任务、问题、里程碑、论坛、活动）
- 用户管理
- 列出门户或项目中的用户
先决条件
- Node.js (v18 或更高版本)
- Zoho Projects 账户 通过API访问
- Zoho OAuth 凭据
设置
1. 获取Zoho OAuth凭据（详细指南）
步骤1：创建一个Zoho开发者应用程序
- 首选 Zoho API控制台
- 点击 “Add Client”翻译成中文是“添加客户端” 按钮
- 选择 “Self Client”可以翻译为“自助客户端”或“自我客户端”，具体取决于上下文和使用场景。在这里，我选择了“自助客户端”作为翻译，因为它更常用于描述一种用户可以自行操作的软件或系统界面 （建议个人使用）或 “基于服务器的应用程序”
- 填写申请详情：
- 客户名称例如，“Zoho Projects MCP” - 主页网址您的网站或 http://localhost 用于测试 - 授权重定向URI： http://localhost:8080/callback （或您偏好的重定向URL）
- 点击 “创造” 并记下：
- 客户端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} 与您的地区：
- 美国： com - 欧盟： eu - 在……里面 in - AU：（此处“AU”可能是一个缩写或特定语境下的术语，没有具体上下文难以给出准确翻译，但一般可理解为“澳大利亚”或根据具体语境翻译为其他含义） com.au - CN:（此处“CN”通常代表“中国”的英文缩写，但在此上下文中可能仅作为一个标识或代码使用，因此直接翻译为“中国”或保留原样“CN”均可，具体取决于上下文需求。若需更具体的翻译，请提供更多上下文信息。） com.cn
- 在您的浏览器中打开此URL
- 登录您的Zoho账户并授权该应用程序
- 您将被重定向到您的重定向URI，并附带一个 代码 URL中的参数：
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"
}重要： 保存这两个令牌：
- 访问令牌有效期1小时（由服务器自动刷新）
- 刷新令牌长期有效，用于获取新的访问令牌
步骤4：查找您的门户ID
方法1：从URL
- 在浏览器中访问您的Zoho Projects
- 看看这个网址：
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. 设置与安装
cd zoho-mcp
2. Create `.env` file with your credentials:cp .env.example .env
Edit .env with your credentials
3. Run with Docker Compose:
**For HTTP Server (remote access):**docker-compose --profile http up -d
**For Stdio Server (local/Claude Desktop):**docker-compose --profile stdio up
4. Check the server is running:For HTTP server
curl http://localhost:3001/health
View logs
docker-compose logs -f
-->
#### Node.js 安装设置
**先决条件：**
- Node.js（v18或更高版本）
**步骤：**
1. 克隆并安装：
git clone cd zoho-mcp npm install npm run build
2. 创建 `.env` 附上您的凭证文件（见下文“配置”部分）
1. 启动服务器：
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` - 获取所有门户
1. `get_portal` - 获取门户详情
1. `list_projects` - 列出所有项目
1. `get_project` - 获取项目详情
1. `create_project` - 创建一个新项目
1. `update_project` - 更新一个项目
1. `delete_project` - 删除一个项目
1. `list_tasks` - 列出任务
1. `get_task` - 获取任务详情
1. `create_task` - 创建一个任务
1. `update_task` - 更新任务
1. `delete_task` - 删除任务
1. `list_issues` - 列出问题
1. `get_issue` - 获取问题详情
1. `create_issue` - 创建一个问题
1. `update_issue` - 更新一个问题
1. `list_phases` - 列出阶段/里程碑
1. `create_phase` - 创建一个阶段
1. `search` - 搜索门户或项目
1. `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的文档