🚀 Zoho Projects MCP Server
このサーバーは、Model Context Protocol (MCP) を使用して、Zoho Projects API との統合を提供します。AIアシスタントが、プロジェクト、タスク、問題、マイルストーンなどの管理のためにZoho Projectsと対話できるようになります。
✨ 主な機能
サポートされる操作
-
ポータル管理
-
プロジェクト管理
- プロジェクトを一覧表示
- プロジェクトの詳細を取得
- 新しいプロジェクトを作成
- 既存のプロジェクトを更新
- プロジェクトを削除(ゴミ箱に移動)
-
タスク管理
- タスクを一覧表示(ポータルまたはプロジェクトレベル)
- タスクの詳細を取得
- タスクを作成
- タスクを更新
- タスクを削除
-
問題管理
- 問題を一覧表示(ポータルまたはプロジェクトレベル)
- 問題の詳細を取得
- 問題を作成
- 問題を更新
-
フェーズ/マイルストーン管理
-
検索
- ポータルまたはプロジェクト全体で検索
- モジュール(プロジェクト、タスク、問題、マイルストーン、フォーラム、イベント)でフィルタリング
-
ユーザー管理
📦 インストール
前提条件
- Node.js (v18以上)
- APIアクセスが有効なZoho Projectsアカウント
- Zoho OAuth資格情報
1. Zoho OAuth資格情報の取得(詳細ガイド)
ステップ1: Zoho開発者アプリケーションの作成
- Zoho APIコンソールにアクセスします。
- "Add Client" ボタンをクリックします。
- "Self Client"(個人使用を推奨)または "Server-based Applications" を選択します。
- アプリケーションの詳細を入力します。
- Client Name: 例えば、"Zoho Projects MCP"
- Homepage URL: あなたのウェブサイト、またはテスト用の
http://localhost
- Authorized Redirect URIs:
http://localhost:8080/callback(またはあなたが選択したリダイレクトURL)
- "Create" をクリックし、以下の情報をメモします。
- Client ID(例:
1000.XXXXXXXXXX)
- Client Secret(これは安全に保管してください!)
ステップ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} をあなたのリージョンに置き換えます。
- US:
com
- EU:
eu
- IN:
in
- AU:
com.au
- CN:
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"
}
重要: 両方のトークンを保存してください。
- access_token: 1時間有効(サーバーによって自動更新されます)
- refresh_token: 長期間有効、新しいアクセストークンを取得するために使用されます
ステップ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
リージョン固有のドメイン:
- US:
projectsapi.zoho.com / accounts.zoho.com
- EU:
projectsapi.zoho.eu / accounts.zoho.eu
- IN:
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の構成
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のドキュメントを確認してください。