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 的文檔