convez.ai
MCP ServerProdutividadeIntermediário
tachibanayu24

Google Tasks MCP para Cloudflare Workers

tachibanayu24/google-tasks-mcp

Google Tasks via MCP remoto em Cloudflare Workers, pronto para Claude Mobile

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP remoto que expõe a API do Google Tasks via Streamable HTTP em Cloudflare Workers. Oferece 15 ferramentas para leitura, escrita e gerenciamento de listas de tarefas, com suporte nativo a Custom Connectors do Claude Mobile.

Instalação

$npx convez-ai tachibanayu24/google-tasks-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Gerenciar tarefas do Google Tasks diretamente pelo Claude Mobile
  • Automatizar criação, atualização e reordenação de tarefas via agentes IA
  • Integrar Google Tasks em fluxos de produtividade sem deixar o Claude

Veredito

Implementação técnica sólida e completa da API Google Tasks com suporte a Cloudflare Workers. Seu destaque é o transporte Streamable HTTP que funciona nativamente em Claude Mobile, cobrindo 15 operações (leitura, escrita e CRUD de listas). Excelente para quem quer automação de tarefas sem sair do mobile.

README

A tradução para o português deste README ainda está na fila.

google-tasks-mcp

Cloudflare Workers 上で動く Google Tasks 向けの Remote MCP サーバ。 Streamable HTTP transport で、Claude の iOS / Android アプリの Custom Connector から直接タスクを読み書きできる。

個人用途・MIT License。モバイル対応 Remote MCP の構築パターンを一通り揃えた実装例として公開。姉妹プロジェクト: fitbit-googlehealth-mcp。


何ができるか

15 個の MCP ツールで Google Tasks API を網羅:

Read (5)

Toolやること
list_tasklistsタスクリスト一覧取得
get_tasklist特定リストのメタデータ取得
list_tasksタスク一覧 (showCompleted/showHidden/showDeleted/期限フィルタ)
list_completed完了・clear_completed 済みタスク一覧 (list_tasks では見えない hidden を含む)
get_task単一タスクの全フィールド

Write (7)

Toolやること
create_taskタスク作成 (parent / previous でサブタスク化・並び順指定)
update_taskタスク部分更新 (PATCH、status 以外)
complete_task完了化 (Google が completed 自動セット)
uncomplete_task未完了に戻す (completed を明示的に null に)
move_task並び替え・サブタスク化・リスト間移動
delete_task物理削除
clear_completed完了タスクを hidden=true に (物理削除ではない)

TaskList CRUD (3)

Toolやること
create_tasklist新規タスクリスト作成
update_tasklistタスクリスト名変更
delete_tasklistタスクリスト削除 (含まれるタスクも全て消える)

既存 OSS との比較

TransportデプロイTool 数movetasklist CRUDClaude モバイル
zcaceres/gtasks-mcpstdioローカル7✗✗✗
arpitbatra123/mcp-googletasksstdioローカル15✓✓✗
gsdv/google-tasks-mcpStreamable HTTPNode/HTTP6✗✗◯
google-tasks-mcp (本プロジェクト)Streamable HTTPCloudflare Workers15✓✓◯

Google Tasks API 特有の挙動 (due は時刻破棄 / clear_completed は hide / hidden と deleted の違い / assignment タスクの移動制約) は、ツールの description と Zod schema、GoogleApiError の hint で吸収している。


前提

  • Google アカウント (Google Tasks を普段使いしているもの)
  • Google Cloud OAuth Client: Desktop app タイプ (ループバック callback は自動許可なので redirect URI の事前登録は不要)
  • Google Tasks API を同プロジェクトで有効化
  • Cloudflare Workers (Free プランで十分) + wrangler CLI でログイン済み
  • Node.js 20+ / pnpm 9+

セットアップ 5 ステップ

1. Clone + install

git clone https://github.com/tachibanayu24/google-tasks-mcp.git
cd google-tasks-mcp
pnpm install

2. Google Cloud OAuth Client を作成

  1. Google Cloud Console で新規プロジェクトを作成 (または既存を選択)
  2. API とサービス → ライブラリ で Google Tasks API を有効化
  3. API とサービス → OAuth 同意画面 を設定
    • User Type: 外部
    • ⚠️ 設定後、「アプリを公開」で公開ステータスを「本番環境 (In production)」にすること。 「テスト (Testing)」のままだと Google が refresh_token を 7 日で失効させ、1 週間ごとに再認可が必要になる。auth/tasks は sensitive scope だが Google の verification は不要 (認可時に「未確認のアプリ」警告が出るだけ)。本番ステータスで発行した refresh_token は revoke / 6 ヶ月未使用 / パスワード変更まで生き続ける。
    • (テストモードのまま試す場合のみ、テストユーザーに自分の Google アカウントを追加。ただし上記の 7 日失効に注意。)
  4. API とサービス → 認証情報 → + 認証情報を作成 → OAuth クライアント ID
    • アプリケーションの種類: デスクトップ アプリ
    • 名前は任意 (例: google-tasks-mcp-cli)
    • → 作成
    • ℹ️ デスクトップ アプリ タイプではリダイレクト URI 設定欄は UI に出てこない。ループバック (http://127.0.0.1:* / http://localhost:*) は自動許可されるため事前登録は不要 (Google 公式ドキュメント)。
  5. 発行された クライアント ID と クライアント シークレット をメモ

3. 初回 OAuth 認可 (ローカル 1 回だけ)

export GOOGLE_CLIENT_ID="<上記のClient ID>"
export GOOGLE_CLIENT_SECRET="<上記のClient secret>"
pnpm run setup:google-tasks

ブラウザが開いて Google 認可画面 → 承認すると 127.0.0.1:8787 に戻ってきて、ターミナルに refresh_token と次に実行すべき wrangler コマンド群が表示される。

4. Cloudflare Workers に投入

4-1. wrangler.toml を自分用に作成

cp wrangler.toml.example wrangler.toml
# ↓ KV ID を差し込む
pnpm wrangler kv:namespace create TOKENS
# 出力された id を wrangler.toml の `id = "<your-tokens-namespace-id>"` に貼り付け

4-2. Secrets 投入

pnpm wrangler secret put GOOGLE_CLIENT_ID
pnpm wrangler secret put GOOGLE_CLIENT_SECRET
pnpm wrangler secret put MCP_SHARED_SECRET   # `openssl rand -base64 32` で生成

4-3. KV にトークン投入

setup CLI の stdout に出た wrangler kv key put コマンドをそのまま実行。wrangler v4 では kv key put のデフォルトが --local (simulator) に変わっているので --remote を付け忘れると本番 KV に届かない (秘蔵の落とし穴)。

pnpm wrangler kv key put --remote --binding=TOKENS refresh_token '1//0g...'
pnpm wrangler kv key put --remote --binding=TOKENS access_token  'ya29...'
pnpm wrangler kv key put --remote --binding=TOKENS expires_at    '1760000000'

確認:

pnpm wrangler kv key list --remote --binding=TOKENS
# → refresh_token / access_token / expires_at が並んでいれば OK

5. Deploy + Claude.ai に登録

pnpm run deploy   # `pnpm deploy` は pnpm のビルトインに吸われるので `run` 必須

→ https://google-tasks-mcp.<your-subdomain>.workers.dev が公開される。

Claude.ai (Web) → Settings → Custom Connectors → Add custom connector で以下の URL を登録:

https://google-tasks-mcp.<your-subdomain>.workers.dev/mcp/<MCP_SHARED_SECRETの値>

追加後は iOS / Android の Claude アプリからも同じ Connector が使える (モバイル側では Custom Connector の新規追加はできないため、必ず Web で先に登録すること)。


アーキテクチャ

Claude mobile/desktop
      │
      │ Streamable HTTP
      ▼
┌────────────────────────────────────────────────────┐
│ Cloudflare Worker (google-tasks-mcp)              │
│                                                    │
│  POST /mcp/:secret                                │
│    ↓ guardMiddleware                              │
│       ├── SECRET 定時間比較                       │
│       └── CF-Connecting-IP ∈ 160.79.104.0/21      │
│    ↓ @hono/mcp StreamableHTTPTransport            │
│    ↓ McpServer (15 tools)                         │
│    ↓ GoogleTasksProvider                          │
│    ↓ GoogleTasksClient                            │
│       ├── getAccessToken (60s-before refresh)     │
│       ├── 401 → refresh → retry                   │
│       └── 429 → Retry-After sleep → retry         │
│                                                    │
│  KV: TOKENS { access_token, refresh_token,         │
│                expires_at }                        │
└────────────────────────────────────────────────────┘
      │ Bearer token
      ▼
  Google Tasks API
  https://tasks.googleapis.com/tasks/v1/

特徴:

  • Worker 側は OAuth の AuthZ code flow を踏まない (CLI bootstrap 経由で事前取得した refresh_token だけを持つ)。Claude 側に OAuth プロキシを提供する必要がないため構造がシンプルで、モバイル WebView の disallowed_useragent ポリシー問題も回避できる。
  • Secret を URL path に入れる + Anthropic outbound CIDR 限定の二層。個人用途として必要十分。

セキュリティモデル

脅威防御
URL を知らない第三者のアクセスMCP_SHARED_SECRET を URL path に置き timing-safe 比較
secret 漏洩時の他 IP からのアクセスCF-Connecting-IP が Anthropic outbound CIDR (160.79.104.0/21) に含まれるかで二層目の制限
Google OAuth token の漏洩wrangler kv と wrangler secret (暗号化保存)。.dev.vars と wrangler.toml は .gitignore
refresh_token の revocationGoogleAuthError 発生時は Claude にヒントを返して setup:google-tasks の再実行を促す

トラブルシュート: 認証が切れたとき

Claude から Google Tasks にアクセスできなくなった場合 (GoogleAuthError / refresh 失敗)、ほぼ refresh_token の失効。KV にトークン 3 点が揃っていても Google 側で無効化されていれば起きる。

まず根本原因を潰す: OAuth 同意画面の公開ステータスが「テスト (Testing)」だと refresh_token は 7 日で失効する。OAuth 同意画面 を開き、「本番環境 (In production)」に公開しておく (セットアップ手順 2-3 の ⚠️ 参照)。

復旧手順 (Worker のコードは無変更なので deploy 不要、KV だけ差し替え):

export GOOGLE_CLIENT_ID="<Client ID>"
export GOOGLE_CLIENT_SECRET="<Client secret>"
pnpm run setup:google-tasks
# → ブラウザで承認 → 出力された `wrangler kv key put --remote` 3 本をそのまま実行

client_secret は Worker secret なので読み出せない (KV の refresh_token だけを手で直すことは不可)。必ず setup を再実行して新しいトークン一式を取り直すこと。本番ステータスで発行した refresh_token は revoke / 6 ヶ月未使用 / パスワード変更まで失効しない。


ローカル開発

pnpm dev       # wrangler dev (port 8787)
pnpm test      # vitest
pnpm typecheck # tsc --noEmit
pnpm lint      # biome check
pnpm format    # biome format --write

MCP Inspector での動作確認:

npx @modelcontextprotocol/inspector
# URL: http://localhost:8787/mcp/dev-secret
# Headers: CF-Connecting-IP: 160.79.105.42

既知の落とし穴 (MCP 層で吸収済み)

Google Tasks API 側どう扱うか
due の時刻は破棄されるnormalizeDue() で YYYY-MM-DD → YYYY-MM-DDT00:00:00.000Z に正規化
clear_completed は物理削除でなく hide 化ツール名と description で明示、list_completed を別ツールで提供
showCompleted=true でも hidden は出ないlist_completed 内部で showHidden=true 固定
サブタスクは 1 階層のみdescription で警告
繰り返し/割り当てタスクは移動制限GoogleApiError の 400 hint でその旨通知
update_task の status と complete_task の責務重複update_task から status 引数を物理的に除外し complete_task / uncomplete_task に誘導

Fitbit MCP との関係

姉妹プロジェクト fitbit-googlehealth-mcp と同じアーキテクチャ・同じ認証パターン・同じコード規約:

  • src/auth/guard.ts (SECRET + CIDR) は両プロジェクトで同一
  • src/lib/rate-limit.ts (Retry-After クランプ) も同一
  • Provider 層の構造 (oauth.ts / client.ts / types.ts) は 1:1 対応
  • Setup CLI (scripts/setup-*.ts) のフロー (localhost callback → code → token) も同一

違いは:

  • Fitbit は Basic auth + form body / Google は body に client_id + client_secret
  • Fitbit は intraday 等でキャッシュ (CACHE KV) が有効 / Google Tasks は軽量なので v0 では CACHE なし
  • Fitbit tokens には user_id がある / Google Tasks にはない

License

MIT. See LICENSE.

Ver o original no GitHub

Bom para

Relacionados