Google Tasks MCP Server

Google Tasks MCP Server

Google Tasks 用の Model Context Protocol（MCP）サーバーです。AI アシスタントが MCP プロトコルを通じて Google Tasks を操作できるようにします。

機能

• タスクリストの一覧表示、作成、更新、削除
• タスクの一覧表示、検索、作成、更新、削除、移動
• 親子関係によるタスクの整理
• タスクの詳細情報の表示
• 完了したタスクの整理
• トークンの自動更新に対応した OAuth2 認証
• パフォーマンス向上のための API リクエストの並列処理
• 型安全性を確保する TypeScript インターフェース
• 包括的なエラー処理
• MCP を介した AI アシスタントとの連携

インストール

# Clone the repository
git clone https://github.com/overlay-one/google-tasks-mcp-server.git
cd google-tasks-mcp-server

# Install dependencies
pnpm install

# Build the project
pnpm build

設定

Google Cloud API アクセスの設定

1. Google Cloud Console でプロジェクトを作成します。
2. Google Tasks API を有効にします。
   • API ライブラリに移動します
   • 「Tasks API」を検索します
   • 「有効にする」をクリックします
3. OAuth 2.0 認証情報を作成します。
   • 「認証情報」に移動します
   • 「認証情報を作成」をクリックし、「OAuth クライアント ID」を選択します
   • アプリケーションの種類として「ウェブアプリケーション」を選択します
   • リダイレクト URI（例：http://localhost:3000/oauth2callback）を追加します
   • 作成後、クライアント ID とクライアントシークレットを控えておきます

環境設定

1. .env.example を .env にコピーします。

cp .env.example .env

2. .env ファイルを編集し、Google API 認証情報を設定します。

# Required credentials
CLIENT_ID=your-client-id
CLIENT_SECRET=your-client-secret
REDIRECT_URI=http://localhost:3000/oauth2callback

# Optional tokens (if you already have them)
# ACCESS_TOKEN=your-access-token
# REFRESH_TOKEN=your-refresh-token

# Optional server configuration
# LOG_LEVEL=info     # Options: error, warn, info, debug

認証方法

このサーバーは、次の 2 つの認証方法に対応しています。

1. 環境変数：.env ファイルで ACCESS_TOKEN と REFRESH_TOKEN を設定します
2. 認証情報ファイル：サーバーはトークンを .credentials.json ファイルに保存できます

このサーバーには、トークンを自動更新する機能が備わっています。アクセストークンの有効期限が切れると、サーバーは次の処理を行います。

1. リフレッシュトークンを自動的に使用して、新しいアクセストークンを取得します
2. メモリ内の認証情報を更新します
3. ファイルベースのストレージを使用している場合は、更新されたトークンを .credentials.json に保存します

使用方法

サーバーの起動

# Production mode
pnpm start

# Development mode (with auto-reloading)
pnpm dev

Claude Desktop での使用

Claude Desktop はこの MCP サーバーと連携し、Google Tasks に直接アクセスできます。この連携により、Claude と自然言語で会話しながらタスクを管理できます。

Claude と Google Tasks を使用するメリット

• 自然言語によるタスク管理：日常的な言葉を使って、タスクの作成、検索、整理ができます
• 文脈の理解：期限について「明日」や「来週」と伝えたとき、Claude が意図を理解します
• タスクの優先順位付けを支援：タスクの整理や優先順位付けについて、Claude に相談できます
• インテリジェント検索：完全一致するキーワードだけでなく、文脈や意味に基づいてタスクを検索できます
• 一括操作：複数のタスクを一度に作成または変更するよう、Claude に依頼できます
• スケジュール設定を支援：既存のタスクに基づいて、最適な期限を Claude が提案できます
• タスクの要約：複数のリストにまたがるタスクの簡潔な要約を取得できます
• 毎日の計画：現在のタスクに基づいて、その日の計画を立てるよう Claude に依頼できます

セットアップ手順

連携の設定方法は次のとおりです。

1. Google Tasks MCP サーバーを起動します。

   pnpm start
   

   サーバーは標準入力／出力チャネル（stdio）で実行されます。

2. MCP サーバーに接続して Claude Desktop を起動します。

   claude mcp --command "node /path/to/google-tasks-mcp-server/dist/index.js"
   

   /path/to/google-tasks-mcp-server を、インストール先の実際のパスに置き換えてください。

3. 別の方法：設定ファイルを作成します。 ホームディレクトリまたはプロジェクトディレクトリに claude.yaml という名前のファイルを作成します。

   mcp:
     command: node /path/to/google-tasks-mcp-server/dist/index.js
   

   その後、claude を実行するだけで、設定済みの MCP サーバーを使用できます。

4. Claude Desktop 内で： 接続すると、Claude はカスタム MCP リソースとツールを通じて Google Tasks にアクセスできるようになります。Claude に次のように依頼できます。

   • 「タスクリストを表示して」
   • 「『プロジェクトレポートを完成させる』という新しいタスクを作成して」
   • 「会議に関連するタスクをすべて探して」
   • 「『ドキュメントを確認する』タスクを完了済みにして」

Claude は、依頼に応じて MCP サーバーを使用し、Google Tasks のデータにアクセスします。

Claude との会話例

接続後、Claude とは次のような会話ができます。

タスクの一覧表示：

You: Show me all my tasks
Claude: I'll retrieve your tasks from Google Tasks.
[Claude uses task.list tool]
Here are your current tasks:
- Complete project documentation (Due: 2025-05-10)
- Schedule team meeting (Due: Not set)
- Review quarterly report (Due: 2025-05-15)

タスクの作成：

You: Create a new task called "Send follow-up email" due tomorrow at 3 PM
Claude: I'll create that task for you.
[Claude uses task.create tool]
I've created a new task:
Title: Send follow-up email
Due: 2025-05-06T15:00:00Z
Status: needsAction

タスクの検索：

You: Find all tasks related to "meeting"
Claude: I'll search for tasks containing "meeting".
[Claude uses task.search tool]
I found 2 tasks related to "meeting":
- Schedule team meeting (Due: Not set)
- Prepare meeting agenda (Due: 2025-05-08)

タスクリストの管理：

You: Create a new task list called "Personal Projects"
Claude: I'll create that task list for you.
[Claude uses tasklist.create tool]
I've created a new task list named "Personal Projects".
Would you like me to add any tasks to this list?

高度な使用例

Google Tasks で Claude を活用する高度な方法をいくつか紹介します。

プロジェクト計画

You: I need to plan a website launch. Can you help me create tasks for it?
Claude: I'd be happy to help plan your website launch. Let me create a task list and relevant tasks.
[Claude uses tasklist.create and task.create tools]
I've created a new task list "Website Launch" with the following tasks:
1. Finalize website content (Due: 1 week from now)
2. Complete design review (Due: 10 days from now)
3. Run final QA tests (Due: 2 weeks from now)
4. Prepare marketing materials (Due: 2 weeks from now)
5. Configure analytics (Due: 3 days before launch)
6. Launch website (Due: 3 weeks from now)
Would you like me to add more specific tasks?

タスクの整理と優先順位付け

You: I have too many tasks. Can you help me prioritize them?
Claude: I'll help you organize and prioritize your tasks.
[Claude uses task.list tool]
Based on your current tasks, here's a suggested prioritization:

High Priority (Complete today):
- Submit quarterly report (Due: Today)
- Call client about project delay (Due: Today)

Medium Priority (Complete this week):
- Prepare presentation (Due: In 3 days)
- Review team metrics (Due: In 5 days)

Low Priority (Can be scheduled later):
- Research new tools (Due: Next week)
- Update documentation (Due: In 2 weeks)

Would you like me to update the due dates to reflect these priorities?

定期的なタスク管理

You: What tasks should I focus on today?
Claude: Let me check your tasks due today or overdue.
[Claude uses task.list and task.search tools]
Here are the tasks you should focus on today:

Due Today:
- Prepare client meeting agenda
- Submit expense report

Overdue:
- Follow up on pending approvals (Due yesterday)

Upcoming Soon:
- Project proposal draft (Due tomorrow)

Should I mark any of these as completed?

Claude Desktop との連携に関するトラブルシューティング

Claude Desktop を Google Tasks MCP サーバーに接続する際に問題が発生した場合は、次の点を確認してください。

1. 認証の問題：

   • .env ファイルに正しい CLIENT_ID、CLIENT_SECRET、REDIRECT_URI が設定されていることを確認します
   • .env または .credentials.json に有効なリフレッシュトークンがあることを確認します
   • 必要に応じて、Google OAuth の手順に従ってトークンを再生成します

2. 接続の問題：

   • Claude に接続する前に、pnpm start でサーバーが起動していることを確認します
   • claude mcp --command のパスが正しいことを確認します
   • 設定ファイルを使用している場合は、YAML の構文が正しいことを確認します

3. コマンドが見つからない：

   • Claude Desktop CLI が PATH に含まれていることを確認します
   • Claude の実行ファイルをフルパスで指定してみてください

4. MCP プロトコルのエラー：

   • 通常、サーバーで内部エラーが発生した場合に表示されます
   • サーバーログを確認して、具体的なエラーの詳細を調べます
   • Claude Desktop と MCP SDK の互換性のあるバージョンを使用していることを確認します

API リファレンス

リソース

サーバーはカスタム URI スキームを通じてリソースを提供します。

タスクリストのリソース

• gtasklists:///：すべてのタスクリストを一覧表示します
• gtasklists:///{taskListId}：ID を指定して特定のタスクリストにアクセスします

タスクのリソース

• gtasks:///：すべてのタスクリストにあるすべてのタスクを一覧表示します
• gtasks:///default：デフォルトのタスクリストにあるタスクを一覧表示します
• gtasks:///{taskId}：ID を指定して特定のタスクにアクセスします
• gtasks:///{taskListId}/tasks/{taskId}：特定のタスクリスト内の特定のタスクにアクセスします

ツール

サーバーは MCP ツールを通じて次の操作をサポートします。

タスクリストの管理

ツール	説明	必須パラメーター	任意パラメーター
tasklist.list	すべてのタスクリストを一覧表示します	なし	maxResults
tasklist.get	ID を指定してタスクリストを取得します	id	なし
tasklist.create	新しいタスクリストを作成します	title	なし
tasklist.update	タスクリストを更新します	id、title	なし
tasklist.delete	タスクリストを削除します	id	なし

タスクの管理

ツール	説明	必須パラメーター	任意パラメーター
task.search	タイトルまたはメモでタスクを検索します	query	taskListId
task.list	すべてのタスクを一覧表示します	なし	taskListId、cursor
task.get	ID を指定してタスクを取得します	id	taskListId
task.create	新しいタスクを作成します	title	taskListId、notes、due、status、parent
task.update	既存のタスクを更新します	id	taskListId、title、notes、status、due、parent
task.move	タスクを移動します（親または位置を変更します）	id	taskListId、parent、previous
task.delete	タスクを削除します	id	taskListId
task.clear	完了したタスクを消去します	なし	taskListId

操作例

タスクの作成

{
  "name": "task.create",
  "arguments": {
    "title": "Complete project documentation",
    "notes": "Include API reference and setup instructions",
    "due": "2025-05-10T00:00:00.000Z",
    "status": "needsAction"
  }
}

タスクの検索

{
  "name": "task.search",
  "arguments": {
    "query": "documentation",
    "taskListId": "MTIzNDU2Nzg5MA"
  }
}

開発

プロジェクト構成

• src/index.ts：メインのサーバー実装と MCP プロトコルハンドラー
• src/Tasks.ts：タスクおよびタスクリストのリソースとアクションの実装
• src/types.ts：リクエストとレスポンスの処理に使用する TypeScript インターフェース
• test/：サーバーコンポーネントの単体テスト

TypeScript の型

このプロジェクトでは、型安全性を確保するために TypeScript のインターフェースを使用しています。主なインターフェースは次のとおりです。

• リクエストパラメーターの型：すべてのツールパラメーターの型を定義する TypeScript インターフェース
  • TaskCreateParams、TaskUpdateParams、TaskSearchParams など
• リソースの型：リソース表現のインターフェース
  • TaskResource、TaskListResource
• ユーティリティの型：Google Tasks API の操作に役立つヘルパー型

これらのインターフェースにより、Google Tasks API にパラメーターを渡す際やレスポンスを処理する際の型安全性を確保できます。

エラー処理

サーバーには、次の処理を行う一貫したエラー処理システムが実装されています。

1. HTTP エラーコードを適切な MCP エラーコードに対応付けます
2. 操作のコンテキストを含む詳細なエラーメッセージを提供します
3. 並列 API 呼び出しで発生したエラーを適切に処理します

パフォーマンスの最適化

サーバーでは、複数のタスクリストに関わる操作に並列 API 呼び出しを使用しています。

• TaskResources.list() と TaskActions._list() では、複数のリストからタスクを並列に取得します
• 一部のタスクリストへのリクエストが失敗した場合も、結果を適切に統合します
• これにより、多数のタスクリストを使用するユーザーのパフォーマンスが大幅に向上します

テスト

このプロジェクトには、Node.js 組み込みのテストランナーを使用するテストフレームワークが含まれています。

# Run all tests (this will first build the TypeScript code)
pnpm test

# Run tests in watch mode for development
pnpm test:watch

初めてテストを実行する前に、依存関係がインストールされていることを確認してください。

pnpm install

テストスイートには、次のテストが含まれています。

• 認証テスト：トークンの更新処理を検証します
• タスク操作テスト：タスク API の機能を検証します
• エラー処理テスト：エラーが適切に処理されることを確認します

テストは JavaScript で記述され、コンパイル済みの TypeScript コードに対して実行されるため、本番コードが想定どおりに動作することを確認できます。テストはモック化された依存関係を使用するよう設計されているため、テスト中に実際の Google API 呼び出しは行われません。

ビルド

pnpm build

開発モードでの実行

pnpm dev

ライセンス

Apache-2.0