使用说明

Zoho项目MCP服务器

用于Zoho Projects API集成的增强型模型上下文协议（MCP）服务器。该服务器使AI助手能够与Zoho Projects交互，以管理项目、任务、问题、里程碑、评论、附件等。

注：这是一个增强的分支，具有按前缀查找任务、任务列表管理、注释、附件和内联图像处理的附加功能。基于 qpiai/zoho项目mcp.

特性

支持的操作

门户网站管理
- 列出所有门户
- 获取门户详细信息
项目管理
- 列出项目
- 获取项目详细信息
- 创建新项目
- 更新现有项目
- 删除项目（移至回收站）
任务管理
- 列出任务（门户或项目级别）
- 获取任务详细信息
- 按前缀/键查找任务 （例如。， CA6-T282) ⭐
- 创建任务
- 更新任务（支持状态和任务列表）
- 删除任务
任务列表管理 ⭐
- 创建任务列表
- 在任务列表之间移动任务
- 删除任务列表
任务备注 ⭐
- 列出对任务的评论
- 向任务添加评论
- 编辑现有评论
任务附件 ⭐
- 将文件附件上传到任务
- 列出任务附件
- 从任务描述中下载内联图像
- 从HTML描述中提取图像URL
问题管理
- 列出问题（门户或项目级别）
- 获取问题详细信息
- 创建问题
- 更新问题
阶段/里程碑管理
- 列出阶段
- 创建阶段
任务状态 ⭐
- 列出项目的可用状态
搜索
- 跨门户或项目搜索
- 按模块筛选（项目、任务、问题、里程碑、论坛、事件）
用户管理
- 列出门户或项目中的用户

其他增强功能⭐

自动刷新OAuth令牌 -不再需要手动令牌管理
空响应处理 -正确处理204无内容响应
API参数映射 -正确处理status_id和tasklist_id

先决条件

Node.js （v18或更高版本）
Zoho项目账户 具有API访问权限
Zoho OAuth凭据

设置

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

步骤1：创建Zoho开发人员应用程序

首选 Zoho API控制台
点击 “添加客户端” 按钮
选择 “自助客户” （建议个人使用）或 “基于服务器的应用程序”
填写申请详情：
- 客户名称：例如，“Zoho项目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： com.au
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小时（由服务器自动刷新）
refresh_token：寿命长，用于获取新的访问令牌

步骤4：查找您的门户ID

方法1：从URL

在浏览器中转到您的Zoho项目
请查看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 使用您的凭据文件（请参阅下面的配置部分）
运行服务器：

# 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： projectsapi.zoho.com.cn / accounts.zoho.com.cn

4.配置克劳德桌面

添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %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

按前缀查找任务⭐

Get the task CA6-T282

向任务添加评论⭐

Add a comment "Work in progress - will complete by EOD" to task 12345 in project 1234567890

上传附件⭐

Upload /path/to/screenshot.png to task 12345 in project 1234567890

将任务移动到不同的任务列表⭐

Move task 12345 to tasklist 67890 in project 1234567890

下载任务图像⭐

Download all images from task CA6-T282 to /tmp/task-images/

项目结构

zoho-projects-mcp/
├── src/
│   └── index.ts          # Main server implementation
├── dist/                  # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
├── FORMATTING.md         # Guide for Zoho HTML formatting
├── CLAUDE.md             # Instructions for Claude Code
└── README.md

可用工具

服务器提供以下MCP工具：

门户和项目

工具	说明
`list_portals`	获取所有门户
`get_portal`	获取门户详细信息
`list_projects`	列出所有项目
`get_project`	获取项目详细信息
`create_project`	创建新项目
`update_project`	更新项目
`delete_project`	删除项目（移至回收站）

任务

工具	说明
`list_tasks`	列出任务（门户或项目级别）
`get_task`	按ID获取任务详细信息
`get_task_by_prefix`	按前缀查找任务（例如。， `CA6-T282`) ⭐
`create_task`	创建任务
`update_task`	更新任务（支持 `status_id`, `tasklist_id`)
`delete_task`	删除任务

任务列表⭐

工具	说明
`create_tasklist`	在项目中创建新任务列表
`move_task`	将任务移动到其他任务列表
`delete_tasklist`	删除任务列表

评论⭐

工具	说明
`list_task_comments`	列出对任务的评论
`add_task_comment`	向任务添加注释
`edit_task_comment`	编辑现有评论

附件和图像⭐

工具	说明
`upload_task_attachment`	将文件附件上载到任务
`list_task_attachments`	列出任务的附件
`download_inline_image`	从任务描述中下载内联图像
`extract_inline_images`	从HTML中提取图像URL
`download_task_images`	从任务描述中下载所有图像

问题

工具	说明
`list_issues`	列出问题（门户或项目级别）
`get_issue`	获取问题详细信息
`create_issue`	创建问题
`update_issue`	更新问题

阶段及其他

工具	说明
`list_phases`	列出阶段/里程碑
`create_phase`	创建阶段
`list_statuses`	列出项目的可用任务状态⭐
`search`	搜索门户或项目
`list_users`	列出门户或项目中的用户

故障排除

身份验证问题

确保您的访问令牌有效且未过期
验证令牌是否具有所需的作用域
检查门户ID是否正确

API错误

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

连接问题

配置更改后重新启动Claude Desktop
检查Claude Desktop日志中的错误消息
验证配置中的服务器路径

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

许可证

麻省理工学院

贡献

欢迎投稿！请随时提交问题或拉取请求。

支持

关于以下问题：

MCP 服务器：在此存储库中打开一个问题
Zoho项目API：联系Zoho支持或查看他们的文档
克劳德桌面版：检查Anthropic的文件