Google Tasks MCP Server

Google Tasks MCP Server

自分で運用するプライベートサーバーを通じて、MCP 対応クライアントを Google Tasks に接続します。このサーバーは、Google Tasks の読み取り、検索、要約、作成、完了、更新、削除、移動を行うコンパクトなツールを公開します。

このプロジェクトはセルフホストでの利用を想定しています。ご自身の Google Cloud OAuth 認証情報を用意し、ご自身の Google アカウントを接続して、トークンを独自の SQLite データベースに保存します。

利用できる機能

• Google Tasks 用の 19 個の MCP ツール。
• デスクトップ／クライアントから起動する構成向けのローカル stdio モード。
• ローカル HTTP または VPS でのホスティング向けの Streamable HTTP モード。
• ベアラートークンによる HTTP 認証に加え、OAuth に対応した MCP クライアント向けのオプションの OAuth 2.0 ゲートウェイモード。
• コンテキストの小さいアシスタントのワークフロー向けに設計されたコンパクトなレスポンス。
• 個人アカウントと仕事用アカウントを使い分けるような、よくある構成に対応する、オプションの運用者管理による複数アカウントのベアラートークンルーティング。

トランスポートを選択する

用途	トランスポート	認証
MCP クライアントがプロセスを直接起動する	stdio	MCP_BEARER_TOKEN は不要
ローカル HTTP サーバー	http://127.0.0.1:8787/mcp の Streamable HTTP	ベアラートークン
VPS またはその他のホスト	https://your-domain.example/mcp の Streamable HTTP	ベアラートークンまたは OAuth ゲートウェイ

ホスティングと配布の詳細については、MCP_SERVER_GUIDE.md と DISTRIBUTION.md を参照してください。

コンテナーの永続化

起動時にファイルシステムが再作成される、ベアラー認証のみの単一アカウント HTTP デプロイでは、 GOOGLE_REFRESH_TOKEN を使って空の SQLite データベースを初期化できます。既存のトークンが 上書きされることはありません。ホスティングプロバイダーのシークレットストアに保管してください。 起動コマンドや Docker のビルド引数には含めないでください。BIND_PORT が未設定の場合、 PORT を提供するホストではその値を使用できます。

OAuth ゲートウェイのデプロイでは、動的に登録されたクライアントと MCP の リフレッシュトークンのハッシュも永続化されます。ホストのファイルシステムが 使い捨ての場合は、イメージの Litestream 変数を設定して、SQLite を S3 互換バケットに 復元・複製してください。コンテナーはサーバーの起動前にデータベースを復元し、 稼働中は変更を複製します。

インストール

git clone https://github.com/ebmurha/google-tasks-mcp.git
cd google-tasks-mcp
python3.11 -m venv .venv
. .venv/bin/activate
pip install -e .
cp .env.example .env

HTTP モードで実行する場合は、ベアラートークンを生成します。

python -c "import secrets; print(secrets.token_urlsafe(48))"

生成された値を .env の MCP_BEARER_TOKEN に設定します。.env をコミットしないでください。

Google Cloud のセットアップ

1. Google Cloud プロジェクトを作成するか、既存のプロジェクトを開きます。
2. Google Tasks API を有効にします。
3. OAuth 同意画面を設定します。
4. OAuth 2.0 クライアント ID を作成します。

ローカル HTTP、VPS、Docker、その他のサーバー形式のインストールでは、次の設定を推奨します。

• アプリケーションの種類：ウェブアプリケーション
• ローカルのリダイレクト URI：http://127.0.0.1:8787/callback
• ホスト環境のリダイレクト URI：https://your-domain.example/callback
• .env：GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET、GOOGLE_REDIRECT_URI を設定

ローカル専用の代替方法：

• アプリケーションの種類：デスクトップアプリ
• OAuth クライアントの JSON をこのリポジトリの外にダウンロードします。
• GOOGLE_OAUTH_KEYS_PATH にそのファイルのパスを設定します。
• JSON ファイルの値を環境変数で上書きする場合を除き、GOOGLE_CLIENT_ID と GOOGLE_CLIENT_SECRET は空のままにします。

ローカルのウェブ OAuth クライアント用の .env の例：

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REDIRECT_URI=http://127.0.0.1:8787/callback
MCP_BEARER_TOKEN=your-generated-token
DB_PATH=./google-tasks.db
BIND_HOST=127.0.0.1
BIND_PORT=8787

Google OAuth アプリがテストモードの場合、個人用と仕事用の両方のアカウントなど、初期設定に使用するすべての Google アカウントをテストユーザーとして追加してください。

GOOGLE_CLIENT_ID／GOOGLE_CLIENT_SECRET／GOOGLE_OAUTH_KEYS_PATH は、Google Cloud OAuth アプリを識別するものであり、Google Tasks のユーザーアカウントを識別するものではありません。1 つの OAuth クライアント JSON を複数の Google ユーザーで再利用できます。初期設定を実行するたびに、ブラウザーで認証した Google アカウントのリフレッシュトークンが個別に保存されます。

Google OAuth の初期設定

ホストされた HTTP オンボーディング

ホスト型サーバーの場合、互いに独立して選んだ次の値を設定します。

GOOGLE_REDIRECT_URI=https://your-domain.example/callback
GOOGLE_OAUTH_ONBOARDING_URL=https://your-domain.example/google/oauth
GOOGLE_OAUTH_SETUP_SECRET=generate-a-long-random-operator-password

公開 URL を明示的に設定してください。アプリケーションは、GOOGLE_OAUTH_ONBOARDING_URL と GOOGLE_REDIRECT_URI で指定されたパスをそのまま提供し、ルートパスのエイリアスは保持しません。MCP ゲートウェイも同様に、MCP_OAUTH_ISSUER と MCP_OAUTH_RESOURCE で宣言されたパスを提供します。リバースプロキシは、これらの公開パスを変更せずに転送します。表示されるオンボーディングリンクにセットアップシークレットが含まれることはありません。

OAuth 対応の MCP クライアントでは、接続または再接続のフローが途切れることなく進行します。サーバー側で MCP の同意が承認されると、設定済みの Google アカウントが確認されます。使用可能な Google 認証情報があれば、そのまま MCP クライアントへ戻ります。Google 認証情報がない、または拒否された場合は、Google の同意フローに進み、Google トークンを SQLite に保存した後、元の OAuth 状態と PKCE バインドを維持したまま同じ MCP クライアントへ戻ります。トークンが表示されたり、コピーを求められたりすることはありません。

GOOGLE_OAUTH_ONBOARDING_URL は、別途パスワードで保護された復旧ページとして引き続き利用できます。オペレーターによる明示的な復旧が必要な場合にのみ、直接開いてください。認証済みの MCP ツールで使用可能な Google トークンが見つからない場合、エラーにはこの安全な復旧 URL が含まれます。

ローカルおよび復旧用 CLI

サーバーにアクセスさせたい Google アカウントごとに、次の操作を一度実行します。

google-tasks-mcp-bootstrap

表示された URL を開いてアクセスを承認し、認証コードをターミナルに貼り付けます。

1 台の HTTP サーバーで複数の信頼できるアカウントを利用する場合は、アカウントごとに保存済みのベアラートークンを作成し、それぞれ個別にブートストラップします。

google-tasks-mcp-create-bearer-token --account-id personal --label "Personal account"
google-tasks-mcp-bootstrap --account-id personal

google-tasks-mcp-create-bearer-token --account-id work --label "Work account"
google-tasks-mcp-bootstrap --account-id work

表示された各ベアラートークンは、対応するアカウントの MCP クライアントでのみ使用してください。サーバーに保存されるのはベアラートークンのハッシュのみです。

サーバーを起動する

HTTP モード：

python -m google_tasks_mcp --transport http

ヘルスチェック：

curl http://127.0.0.1:8787/healthz

想定される応答：

{"ok": true}

Stdio モード：

python -m google_tasks_mcp --transport stdio

設定の確認：

python -m google_tasks_mcp --check

MCP クライアントを接続する

リモートまたはローカルの HTTP：

URL:  http://127.0.0.1:8787/mcp
Auth: Bearer <MCP_BEARER_TOKEN>

VPS の場合は、URL を HTTPS エンドポイントに置き換えます。

URL:  https://your-domain.example/mcp
Auth: Bearer <MCP_BEARER_TOKEN>

ローカル Stdio：

{
  "command": "/path/to/google-tasks-mcp/.venv/bin/python",
  "args": ["-m", "google_tasks_mcp", "--transport", "stdio"]
}

MCP クライアントがプロセスをローカルで起動するため、Stdio では MCP_BEARER_TOKEN は不要です。

認証モード

ベアラートークンモードは、デフォルトの HTTP モードです。/mcp へのアクセスには Authorization: Bearer <token> が必要です。

• MCP_BEARER_TOKEN はアカウント default に割り当てられます。
• google-tasks-mcp-create-bearer-token で作成したトークンを使うと、異なるクライアントを異なる account_id に割り当てられます。
• ベアラートークンは一度だけ表示され、ハッシュのみが保存されます。

OAuth 2.0 ゲートウェイモードは任意です。HTTP MCP クライアントが OAuth 認可メタデータとトークン更新をサポートしている場合に有効にしてください。

• MCP_OAUTH_ISSUER、MCP_OAUTH_CLIENT_ID、MCP_OAUTH_CLIENT_SECRET、MCP_OAUTH_SIGNING_SECRET を設定します。
• MCP_OAUTH_RESOURCE に正規の公開 MCP URL を設定するか、デフォルトの <issuer>/mcp を使用します。
• MCP_OAUTH_REDIRECT_URIS に、MCP クライアントが受け入れるコールバック URI の値を設定します。
• Dynamic Client Registration を使うクライアントの場合は、MCP_OAUTH_ENABLE_DCR=true を設定します。
• ゲートウェイは保護リソースと認可サーバーのメタデータを公開し、PKCE S256 を必須とします。また、トークンを正規のリソースに紐付け、認可リダイレクトに RFC 9207 の発行者識別情報を含めます。
• /mcp は OAuth 発行のアクセストークンと従来のベアラートークンを受け入れます。
• OAuth クライアントシークレットと更新トークンはハッシュのみが保存されます。DB_PATH が永続化される場合、登録済みクライアントとローテーションされる更新トークンは再起動後も保持されます。

公開プロキシ URL、MCP OAuth の発行者／リソース、Google OAuth のコールバックは、運用者が管理するデプロイ設定です。これらは個別に変更できます。サーバーは特定のホスト名を要求せず、所有者固有の URL からこれらの設定を導出することもありません。

MCP OAuth は、このサーバーに対してクライアントを認証します。Google OAuth は、このサーバーが Google Tasks を呼び出すことを個別に認可します。MCP の同意フローはこの 2 つの層を連携させるため、設定された Google アカウントが利用できないと認識されている状態では、接続および再接続が正常に完了しません。明示的な復旧には、スタンドアロンの運用者ページを引き続き利用できます。

OAuth ゲートウェイモードを無効にするには、MCP_OAUTH_REDIRECT_URIS を空のままにします。

ツール

stdio、ベアラートークン HTTP、OAuth ゲートウェイ HTTP の各モードで、同じ 19 個のツールを利用できます。クライアントがサポートしている場合、ツールは標準の MCP タイトル、説明、安全性に関するヒントを公開します。

グループ	ツール	備考
タスクリスト	list_tasklists、create_tasklist、get_tasklist、update_tasklist、delete_tasklist	タスクリストの削除には confirm: true が必要です。空でないリストには force: true が必要です。
タスクの読み取り	list_tasks、get_task	1 つのタスクリストから読み取ります。tasklist を省略した場合は、DEFAULT_TASKLIST または Google の最初のリストを使用します。
タスクの概要	today、overdue、upcoming、search、digest	tasklist を省略した場合は、すべてのタスクリストを読み取り、タスクリストのコンテキストを含めます。
タスクの変更	clear_completed、add、complete、update、uncomplete、delete、move	一度に変更できるのは 1 つのタスクリストまたはタスクです。clear_completed には confirm: true が必要です。

すべての tasklist 引数には、タスクリスト ID または完全一致するタイトルを指定できます。タスクタイトルの検索では、前後の空白を削除した後に完全一致で照合し、大文字と小文字は区別しません。

today、overdue、upcoming、search、digest で tasklist を省略すると、すべてのタスクリストを読み取ります。返されるタスクオブジェクトには tasklist_id と tasklist_title が含まれます。digest では、各項目にタスクリストのコンテキストを付けます。

list_tasks、clear_completed、単一タスクのツール、書き込みツールで tasklist を省略すると、DEFAULT_TASKLIST または Google が返す最初のリストを使用します。これにより、リストを指定しない書き込みがすべてのリストに影響するのを防ぎます。

制限事項

以下は Google Tasks REST API の制限です。

• 期限は日付のみです。Google はタスクの期限に指定された時刻を破棄します。
• Google Tasks REST API では、繰り返しタスクを作成または読み取ることはできません。
• clear_completed は完了済みタスクを非表示にします。完全に削除するものではありません。

Docker と VPS

Docker：

docker compose up --build

.env、OAuth JSON ファイル、SQLite データベースは、イメージや公開バンドルの外部に配置してください。

VPS／systemd／Caddy のテンプレートは deploy/ にあります：

• deploy/caddy/Caddyfile
• deploy/systemd/google-tasks-mcp.service

デプロイする前に、すべてのプレースホルダーのドメイン、パス、ユーザーを置き換えてください。

トラブルシューティング

ベアラートークンがありません：

• HTTP の /mcp では、OAuth ゲートウェイモードがクライアントを処理している場合を除き、Authorization: Bearer <token> が必要です。
• Stdio モードでは MCP_BEARER_TOKEN を使用しません。

Google OAuth アプリがテストモードです：

• ブートストラップしたすべての Google ユーザーをテストユーザーとして追加してください。
• テストモードのリフレッシュトークンは、7 日後に期限切れになることがあります。

コールバック URI が一致しません：

• GOOGLE_REDIRECT_URI は、Google Cloud の承認済みリダイレクト URI と完全に一致する必要があります。
• ローカルのウェブ OAuth では、一貫して http://127.0.0.1:8787/callback を使用してください。

Google のリフレッシュトークンが期限切れ、または取り消されています：

• ホスト型 HTTP の場合は、GOOGLE_OAUTH_ONBOARDING_URL を開いて Google に再接続してください。
• ローカルでの使用または復旧時には、google-tasks-mcp-bootstrap を再実行してください。
• マルチアカウントモードの場合は、以前と同じ --account-id を指定してください。

OAuth MCP クライアントが何度も再認証を求めます：

• サーバーが、永続化された MCP OAuth リフレッシュトークンに対応するバージョンを実行していることを確認してください。
• DB_PATH が永続ストレージを指し、再起動後も保持されることを確認してください。
• MCP_OAUTH_ISSUER が末尾にスラッシュのない、公開 HTTPS ベース URL であることを確認してください。
• MCP_OAUTH_RESOURCE が公開 /mcp URL と完全に一致することを確認してください。
• 使い捨てホストでは、起動前に Litestream が SQLite レプリカを復元したことを確認してください。

その他のドキュメント

• MCP_SERVER_GUIDE.md では、ホスティングモデル、認証情報の境界、公開プロジェクトと公開サービスの選択肢について説明しています。
• DISTRIBUTION.md では、レジストリ、バンドル、ディレクトリへの公開について説明しています。
• .env.example には、サポートされているすべての環境変数が記載されています。
• google-tasks-mcp-specifications.md が動作仕様の正式な情報源です。

テスト

pytest