google-tasks

google-tasks-mcp-server

Google Tasks 用の MCP サーバーです。あらゆる MCP クライアント（Claude Desktop、Claude Code、Codex、Cursor など）から、タスクリストとタスクへの完全な読み書きアクセスが可能です。リスト表示、作成、更新、完了、削除、移動に対応し、実際の期限日も設定できます。

公式の Google Tasks MCP サーバーはないため、このサーバーがその役割を担います。CRUD 操作に完全対応し、OAuth のインストール済みアプリ認証フローを使用します（認証情報が端末の外に出ることはありません）。全体を TypeScript で実装しています。

ツール

タスクリスト

• google_tasks_list_tasklists すべてのタスクリストを表示
• google_tasks_get_tasklist 1 つのタスクリストを取得
• google_tasks_create_tasklist 新しいタスクリストを作成
• google_tasks_update_tasklist タスクリストの名前を変更
• google_tasks_delete_tasklist タスクリストとそのすべてのタスクを削除

タスク

• google_tasks_list_tasks リスト内のタスクを表示。期限日／更新日時によるフィルターとページネーションに対応
• google_tasks_get_task 1 つのタスクを取得
• google_tasks_create_task タスクを作成（サブタスクとして作成することも、配置位置を指定することもできます）
• google_tasks_update_task タイトル／メモ／期限日／ステータスを更新
• google_tasks_complete_task / google_tasks_reopen_task 完了／未完了としてマーク
• google_tasks_delete_task タスクを削除
• google_tasks_move_task タスクの並べ替え、親の変更、別のリストへの移動
• google_tasks_clear_completed_tasks リスト内の完了済みタスクをすべて削除

すべてのツールで response_format: "markdown" | "json" に対応しています。

クイックスタート

npm からインストールする場合：

npm install -g @girmmy/google-tasks-mcp-server

または、インストールせずに npx 経由で MCP クライアントから実行することもできます（ステップ 4 を参照）。

ソースからインストールする場合：

git clone https://github.com/girmmy/google-tasks-mcp-server.git
cd google-tasks-mcp-server
npm install
npm run build

どちらの場合も、以下のセットアップ手順に従って、ご自身の Google OAuth 認証情報を作成し、認証してください。共有版やホスト版はありません。このサーバーはご自身の Google アカウントに直接接続します。

セットアップ

1. Google Cloud OAuth クライアントを作成する

ユーザーごとに独自の OAuth クライアントが必要です。クライアントシークレットを使う人は誰でもアプリになりすませる可能性があるため、共有することはできません（ただし、その場合でも各ユーザー自身の同意が必要です）。

1. Google Cloud Console にアクセスし、プロジェクトを作成するか、既存のプロジェクトを選択します。
2. 「APIs & Services」→「Library」を開き、Google Tasks API を有効にします。
3. 「APIs & Services」→「OAuth consent screen」（Google は現在これを「Google Auth Platform」と呼んでいます）を開きます。
   • ユーザータイプ：個人利用であれば「External」で問題ありません。
   • アプリ名と、サポート／連絡先用のメールアドレスを入力します。
   • 「Audience」→「Test users」で、ご自身の Google アカウントを追加します。アプリのステータスが「Testing」の間は、一覧に登録されたテストユーザーのみが認証できますが、ご自身で実行する分には問題ありません。
4. 「Clients」→「Create Client」→「Application type: Desktop app」の順に選択し、作成します。
5. クライアント ID とクライアントシークレットを取得します。作成直後に「Download JSON」を選択するか、後でクライアントの詳細ページから取得できます。Google のコンソールでは、ページを移動するとシークレットの平文は再表示されず、ダウンロードまたは再生成のみ可能です。紛失した場合は、古いものを探すのではなく、新しいシークレットを追加してください。
6. ファイルを保存します。デフォルトでは、このサーバーは次の場所を参照します。 ~/.config/google-tasks-mcp-server/client_secret.json （GOOGLE_TASKS_CLIENT_SECRET 環境変数でパスを変更できます。たとえば、プロジェクトディレクトリ内の ./credentials/client_secret.json に保存したい場合に便利です。credentials/ はすでに Git の対象外です。）

ファイルは次のような形式です。

{
  "installed": {
    "client_id": "YOUR_CLIENT_ID.apps.googleusercontent.com",
    "client_secret": "YOUR_CLIENT_SECRET",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token",
    "redirect_uris": ["http://localhost"]
  }
}

2. インストール

npm からインストールする場合（ビルド不要）：

npm install -g @girmmy/google-tasks-mcp-server

ソースからインストールする場合：

npm install
npm run build

3. 認証する（初回のみ）

npm からインストールした場合：

google-tasks-mcp-auth
# or without installing anything:
npx -y -p @girmmy/google-tasks-mcp-server google-tasks-mcp-auth

ソースからの場合：

npm run auth
# or, if your client secret lives at a custom path:
GOOGLE_TASKS_CLIENT_SECRET=./credentials/client_secret.json npm run auth

Google の同意 URL が表示され、デフォルトのブラウザーで開こうとします。サインインしてアクセスを許可すると、http://localhost:53682 の短時間だけ起動するローカルサーバーにリダイレクトされます。トークンは ~/.config/google-tasks-mcp-server/token.json にキャッシュされ（GOOGLE_TASKS_TOKEN_PATH で変更できます）、以降は自動で更新されるため、アクセスを取り消さない限り、再度実行する必要はありません。

実際に普段使用するのと同じマシンで、同じ通常のターミナルから実行してください。コンテナー、VM、または localhost がブラウザーに接続できないサンドボックス化されたシェルから実行する場合は、以下の「トラブルシューティング」を参照してください。

4. 実行する

npm start

または、MCP クライアントに設定します。Claude Desktop／Claude Code の場合は、MCP 設定（macOS では通常 ~/Library/Application Support/Claude/claude_desktop_config.json）に追加してください。

npm を使用し、クライアントシークレットがデフォルトの ~/.config/... パスにある場合、設定全体は次のとおりです。

{
  "mcpServers": {
    "google-tasks": {
      "command": "npx",
      "args": ["-y", "@girmmy/google-tasks-mcp-server"]
    }
  }
}

または、ソースのチェックアウト先を指定します。

{
  "mcpServers": {
    "google-tasks": {
      "command": "node",
      "args": ["/absolute/path/to/google-tasks-mcp-server/dist/index.js"],
      "env": {
        "GOOGLE_TASKS_CLIENT_SECRET": "/absolute/path/to/google-tasks-mcp-server/credentials/client_secret.json"
      }
    }
  }
}

クライアントシークレットをデフォルトの ~/.config/... パスに保存した場合は、env ブロックを省略してください。その後、MCP クライアントを完全に終了してから再起動してください。

Codex

Codex では JSON ではなく TOML を使用します。~/.codex/config.toml に以下を追加してください。

[mcp_servers.google-tasks]
command = "npx"
args = ["-y", "@girmmy/google-tasks-mcp-server"]
startup_timeout_sec = 60

または、CLI に設定を書き込ませます。

codex mcp add google-tasks -- npx -y @girmmy/google-tasks-mcp-server

初回起動時にタイムアウトする場合は、startup_timeout_sec の値を大きくしてください。初回の npx は、サーバーが initialize に応答できるようになる前にパッケージをダウンロードするため、Codex のデフォルトの待ち時間では短すぎて、初回のみタイムアウトすることがあります。

クライアントシークレットがデフォルトのパスにない場合は、次を追加してください。

[mcp_servers.google-tasks.env]
GOOGLE_TASKS_CLIENT_SECRET = "/absolute/path/to/client_secret.json"

codex mcp list で登録されたことを確認してください。認証は他の場合と同様、初回のみの google-tasks-mcp-auth 手順で行います。ブラウザーを開いてループバックリダイレクトを受け取る必要があるため、Codex 内ではなく通常のターミナルで実行してください。

環境変数

変数	デフォルト	用途
GOOGLE_TASKS_CLIENT_SECRET	~/.config/google-tasks-mcp-server/client_secret.json	ダウンロードした OAuth クライアント JSON のパス
GOOGLE_TASKS_TOKEN_PATH	~/.config/google-tasks-mcp-server/token.json	キャッシュされた OAuth トークンの保存先
GOOGLE_TASKS_OAUTH_PORT	53682	npm run auth の実行時のみ使用するループバックポート

セキュリティに関する注意

• クライアントシークレットとキャッシュされたトークンは、ディスク上にプレーンファイルとして保存されます（トークンのモードは 0600）。これらをコミットしないでください（.gitignore ではすでに client_secret*.json、token.json、credentials/ を除外しています）。
• サーバーは https://www.googleapis.com/auth/tasks スコープ（読み書き）全体を要求します。読み取り専用アクセスにするには、npm run auth の実行前に src/constants.ts の TASKS_SCOPE を .../auth/tasks.readonly に変更してください。その場合、書き込みツールは Google からの 403 エラーで失敗しますが、これは想定どおりです。
• ツールの注釈では、削除／クリア操作を destructiveHint: true として示し、MCP クライアントが警告したり、実行を制限したりできるようにしています。
• ここでは、Google 独自の API と、npm run auth の実行時に使用するローカルのループバックリスナー以外のサーバーとは通信しません。サードパーティのバックエンドは使用しません。

トラブルシューティング

npm run auth で URL が開き、［許可］をクリックしても処理が止まったままです。 npm run auth を実行しているプロセスと、［許可］をクリックしているブラウザーが、同じマシンまたはネットワーク上にありません。サーバーをコンテナー、リモート開発環境、または localhost を分離するサンドボックス化されたシェル内で実行している場合によくあります。対処方法：使用しているブラウザーがあるマシンの通常のローカルターミナルで、npm run auth を直接実行してください。

Error [TransformError] ... You installed esbuild for another platform 現在使用している OS／アーキテクチャとは異なる環境で node_modules がインストールされています。たとえば、Docker コンテナーや別のマシンからコピーした場合です。対処方法：rm -rf node_modules package-lock.json && npm install を実行してください。

Authorization failed: invalid_client client_secret.json のクライアントシークレットが間違っています。通常、直接ダウンロードせず、手動でコピーして貼り付けた場合に発生します。Google Cloud Console に戻り、新しいクライアントシークレットを追加して、直接ダウンロードするかコピーし、client_secret.json を更新してください。

サーバーが「No cached Google Tasks token found」と表示してすぐ終了します まだ認証していないか、認証フローが完了していません。サーバーを起動する前に、google-tasks-mcp-auth（npm install）または npm run auth（ソースコードをチェックアウトした場合）を実行してください。

開発

npm run dev     # run directly from TypeScript with auto-reload
npm run build   # type-check and compile to dist/

MCP Inspector でテストします：

npx @modelcontextprotocol/inspector node dist/index.js

コントリビューション

Issue や PR を歓迎します。このプロジェクトは Tasks API の全機能をカバーしていますが、すべてのエッジケースでテストされているわけではありません。バグを見つけた場合や機能を追加したい場合は、Issue を作成してください。

ライセンス

MIT。詳しくは LICENSE を参照してください。