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控制台
- 填写申请详情:
- 客户名称例如,“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`
1. 在您的浏览器中打开此URL
1. 登录您的Zoho账户并授权该应用程序
1. 您将被重定向到您的重定向URI,并附带一个 **代码** URL中的参数:```
http://localhost:8080/callback?code=1000.XXXXX.XXXXX&location=in&accounts-server=https://accounts.zoho.in
- 复制
code值(有效期约2分钟,请立即使用!)
步骤3:用代码兑换代币
使用此curl命令来获取您的访问令牌和刷新令牌:```bash
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"
响应将包含:```json
{
"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```bash
curl -X GET https://projectsapi.zoho.{REGION}/api/v3/portals \
-H "Authorization: Zoho-oauthtoken YOUR_ACCESS_TOKEN"
响应将列出所有您的门户及其ID。
#### 步骤5:验证凭据
使用此API调用测试您的设置:```bash
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.milestones.ALL- 里程碑/阶段管理 - ✅
ZohoProjects.users.READ- 用户信息 - ✅
ZohoSearch.securesearch.READ- 搜索功能
2. 设置与安装
Node.js 安装设置
先决条件:
- Node.js(v18或更高版本)
步骤:
- 克隆并安装:```bash
git clone
cd zoho-mcp
npm install
npm run build
2. 创建 `.env` 附上您的凭证文件(见下文“配置”部分)
1. 启动服务器:```bash
# Stdio server (for local MCP clients)
npm start
# HTTP server (for remote access)
npm run start:http
3. 配置
创建一个 .env 在项目根目录中创建一个文件,包含以下变量:```bash
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的设置:```json
{
"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服务器会自动使用刷新令牌来更新令牌。
### 手动刷新令牌
如果您需要手动刷新您的访问令牌:```bash
# 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
响应示例:```json
{
"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服务器会自动处理令牌刷新。请配置以下环境变量:```bash
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文档,请访问:
许可证
麻省理工学院(MIT)
做出贡献
欢迎贡献!请随时提交问题或拉取请求。
支持
对于以下相关问题:
- MCP服务器在这个仓库中打开一个问题(或议题)
- Zoho Projects API联系Zoho支持团队或查阅其文档
- Claude Desktop(中文可译为“Claude桌面版”)查阅Anthropic的文档
