🚀 Zoho Projects MCP 服務器
Zoho Projects MCP 服務器是一個遵循模型上下文協議（MCP）的服務器，可與 Zoho Projects API 集成。藉助該服務器，AI 助手能夠與 Zoho Projects 進行交互，實現項目、任務、問題、里程碑等的管理。
✨ 主要特性
支持的操作
-
門戶管理
-
項目管理
- 列出項目
- 獲取項目詳情
- 創建新項目
- 更新現有項目
- 刪除項目（移至回收站）
-
任務管理
- 列出任務（門戶或項目級別）
- 獲取任務詳情
- 創建任務
- 更新任務
- 刪除任務
-
問題管理
- 列出問題（門戶或項目級別）
- 獲取問題詳情
- 創建問題
- 更新問題
-
階段/里程碑管理
-
搜索
- 在門戶或項目中進行搜索
- 按模塊（項目、任務、問題、里程碑、論壇、事件）進行篩選
-
用戶管理
📦 安裝指南
1. 獲取 Zoho OAuth 憑證（詳細指南）
步驟 1：創建 Zoho 開發者應用
- 訪問 Zoho API 控制檯
- 點擊 “添加客戶端” 按鈕
- 選擇 “自客戶端”（個人使用推薦）或 “基於服務器的應用程序”
- 填寫應用程序詳細信息：
- 客戶端名稱：例如，“Zoho Projects MCP”
- 主頁 URL：您的網站或用於測試的
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
- 澳大利亞：
com.au
- 中國：
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"
}
重要提示：請保存這兩個令牌：
- 訪問令牌：有效期為 1 小時（服務器會自動刷新）
- 刷新令牌：長期有效，用於獲取新的訪問令牌
步驟 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 安裝
前提條件：
步驟：
- 克隆並安裝：
git clone <repository-url>
cd zoho-mcp
npm install
npm run build
-
使用您的憑證創建 .env 文件（請參閱下面的配置部分）
-
運行服務器：
npm start
npm run start:http
3. 配置
在項目根目錄下創建一個 .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.com
ZOHO_ACCOUNTS_DOMAIN=https://accounts.zoho.com
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 工具：
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 服務器會使用刷新令牌自動刷新令牌。
手動刷新令牌
如果您需要手動刷新訪問令牌：
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"
響應示例：
{
"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 的文檔
%20--%3e%3cdefs%3e%3cstyle%3e%20.st0%20{%20fill:%20%23061b40;%20}%20.st1%20{%20fill:%20%23306af1;%20}%20.st2%20{%20fill:%20%235ce5cf;%20}%20%3c/style%3e%3c/defs%3e%3cg%3e%3cpath%20class='st0'%20d='M55,10.5h9v3h-9v9h12V7.5h-12v3ZM64,19.5h-6v-3h6v3Z'/%3e%3cpolygon%20class='st0'%20points='69%2016.5%2078%2016.5%2078%2019.5%2069%2019.5%2069%2022.5%2081%2022.5%2081%2013.5%2072%2013.5%2072%2010.5%2081%2010.5%2081%207.5%2069%207.5%2069%2016.5'/%3e%3cpolygon%20class='st0'%20points='95%2010.5%2095%207.5%2083%207.5%2083%2022.5%2095%2022.5%2095%2019.5%2086%2019.5%2086%2016.5%2095%2016.5%2095%2013.5%2086%2013.5%2086%2010.5%2095%2010.5'/%3e%3cpath%20class='st0'%20d='M40,1.5v21h11.6l1.4-1.4v-7.6h0c0,0-1.4-1.5-1.4-1.5l1.4-1.4V2.9l-1.4-1.4h-11.6ZM50,19.5h-7v-6h7v6ZM50,10.5h-7v-6h7v6Z'/%3e%3c/g%3e%3cpath%20class='st1'%20d='M23.1,24L14.7,4.8l-4.9,11.2h3.8l-1.8,4H3.3L12.1,0H2C.9,0,0,.9,0,2v20c0,1.1.9,2,2,2h21.1Z'/%3e%3cpath%20class='st2'%20d='M34,0h-16.8l10.6,24h6.2c1.1,0,2-.9,2-2V2C36,.9,35.1,0,34,0ZM32.5,20h-4V4h4v16Z'/%3e%3c/svg%3e)
%20--%3e%3cdefs%3e%3cstyle%3e%20.st0%20{%20fill:%20%230080ff;%20}%20%3c/style%3e%3c/defs%3e%3cpath%20class='st0'%20d='M16.2,11.1c.4.5.4,1.2,0,1.8l-4.7,7.1h-3.8l5.3-8L7.6,4h3.8l4.7,7.1Z'/%3e%3c/svg%3e)
