Google Tasks MCP Server

io.github.ebmurha由 GitHub 帳號 ebmurha 發布v0.4.0更新於 Nov 10, 2026

Manage Google Tasks from MCP-compatible AI clients.

已驗證STDIO僅桌面效率與工作流檔案與儲存

概覽

AI 產生的概覽

自架式 MCP 伺服器,讓助理讀取、搜尋、彙整並修改你自己 Google 帳號中的 Google Tasks。

可以做什麼
  • 列出、建立、取得、更新與刪除任務清單,刪除需確認
  • 讀取某個任務清單中的任務並列出任務
  • 透過今日、逾期、即將到期、搜尋與摘要檢視跨清單彙整任務
  • 新增、完成、取消完成、更新、刪除、移動任務以及清除已完成任務
  • 支援本機 stdio 或串流 HTTP,HTTP 可用 Bearer 權杖或選用 OAuth 閘道驗證
適用情境
當你希望 AI 用戶端協助整理與編輯 Google Tasks——查看今天到期或已逾期的任務、搜尋任務、新增或勾選完成項目——同時把憑證與資料留在自己掌控的基礎設施上時使用。
執行需求
需要 Python 3.11 並在本機安裝此套件,或部署為託管 HTTP 服務。需要一個啟用 Tasks API 的 Google Cloud 專案與 OAuth 用戶端,透過 GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET 與 GOOGLE_REDIRECT_URI(或用戶端 JSON 路徑)設定。每個 Google 帳號需執行一次引導授權。HTTP 模式需要 MCP_BEARER_TOKEN;權杖與 OAuth 狀態需要可持久化的 DB_PATH。
安裝前請注意
需要自備 Google OAuth 憑證,並把 Google 更新權杖存放在本機 SQLite 資料庫中,請保護好 DB_PATH、.env 與 OAuth JSON 檔案,不要打包進映像檔或提交到儲存庫。工具可建立、更新、移動與刪除任務及任務清單,刪除與清除已完成需明確的確認參數。Bearer 權杖只顯示一次並以雜湊儲存。測試模式下的 OAuth 更新權杖可能於 7 天後過期。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Google Tasks MCP Server,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

Google Tasks MCP Server

Connect an MCP-compatible client to Google Tasks through a private server you run yourself. The server exposes compact tools for reading, searching, summarizing, creating, completing, updating, deleting, and moving Google Tasks.

This project is for self-hosted use. You provide your own Google Cloud OAuth credentials, connect your own Google account, and keep tokens in your own SQLite database.

What You Get

  • 19 MCP tools for Google Tasks.
  • Local stdio mode for desktop/client-launched setups.
  • Streamable HTTP mode for local HTTP or VPS hosting.
  • Bearer-token HTTP auth, plus optional OAuth 2.0 gateway mode for MCP clients that support OAuth.
  • Compact responses designed for low-context assistant workflows.
  • Optional operator-managed multi-account bearer-token routing, for familiar setups such as one personal account and one work account.

Choose A Transport

Use caseTransportAuth
MCP client starts the process directlystdioNo MCP_BEARER_TOKEN needed
Local HTTP serverStreamable HTTP at http://127.0.0.1:8787/mcpBearer token
VPS or other hostStreamable HTTP at https://your-domain.example/mcpBearer token or OAuth gateway

For deeper hosting and distribution guidance, see MCP_SERVER_GUIDE.md and DISTRIBUTION.md.

Container persistence

For a bearer-only single-account HTTP deployment whose filesystem is recreated on startup, GOOGLE_REFRESH_TOKEN can seed an empty SQLite database. It never overwrites an existing token. Keep it in the hosting provider's secret store; do not put it in a start command or Docker build argument. Hosts that provide PORT can use it when BIND_PORT is unset.

OAuth gateway deployments also persist dynamically registered clients and MCP refresh-token hashes. Configure the image's Litestream variables to restore and replicate SQLite to an S3-compatible bucket when the host filesystem is disposable. The container restores the database before starting the server and replicates changes while it runs.

Install

bash
git clone https://github.com/ebmurha/google-tasks-mcp.gitcd google-tasks-mcppython3.11 -m venv .venv. .venv/bin/activatepip install -e .cp .env.example .env

Generate a bearer token if you will run HTTP mode:

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

Put the generated value in .env as MCP_BEARER_TOKEN. Do not commit .env.

Google Cloud Setup

  1. Create or open a Google Cloud project.
  2. Enable the Google Tasks API.
  3. Configure the OAuth consent screen.
  4. Create an OAuth 2.0 Client ID.

Recommended for local HTTP, VPS, Docker, and other server-style installs:

  • Application type: Web application
  • Local redirect URI: http://127.0.0.1:8787/callback
  • Hosted redirect URI: https://your-domain.example/callback
  • .env: set GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, and GOOGLE_REDIRECT_URI

Local-only alternative:

  • Application type: Desktop app
  • Download the OAuth client JSON outside this repo.
  • Set GOOGLE_OAUTH_KEYS_PATH to that file path.
  • Leave GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET empty unless you want env vars to override the JSON file.

Example .env for a local web OAuth client:

env
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.comGOOGLE_CLIENT_SECRET=your-client-secretGOOGLE_REDIRECT_URI=http://127.0.0.1:8787/callbackMCP_BEARER_TOKEN=your-generated-tokenDB_PATH=./google-tasks.dbBIND_HOST=127.0.0.1BIND_PORT=8787

If the Google OAuth app is in Testing mode, add every Google account you bootstrap as a test user, such as both personal and work accounts.

GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET / GOOGLE_OAUTH_KEYS_PATH identify the Google Cloud OAuth app, not the Google Tasks user account. One OAuth client JSON can be reused for several Google users. Each bootstrap run stores a separate refresh token for the Google account you authorize in the browser.

Bootstrap Google OAuth

Hosted HTTP onboarding

For a hosted server, set these independently chosen values:

env
GOOGLE_REDIRECT_URI=https://your-domain.example/callbackGOOGLE_OAUTH_ONBOARDING_URL=https://your-domain.example/google/oauthGOOGLE_OAUTH_SETUP_SECRET=generate-a-long-random-operator-password

Configure the public URLs explicitly. The application serves the exact paths from GOOGLE_OAUTH_ONBOARDING_URL and GOOGLE_REDIRECT_URI; it does not retain root-path aliases. The MCP gateway likewise serves the paths declared by MCP_OAUTH_ISSUER and MCP_OAUTH_RESOURCE. A reverse proxy forwards these public paths unchanged. The displayed onboarding link never contains the setup secret.

OAuth-capable MCP clients use one continuous Connect or Reconnect flow. After the server's MCP consent is approved, it verifies the configured Google account. A usable Google credential continues directly to the MCP client. A missing or rejected Google credential continues through Google consent, stores the Google token in SQLite, and then returns to the same MCP client with its original OAuth state and PKCE binding. No token is displayed or copied.

GOOGLE_OAUTH_ONBOARDING_URL remains a separately password-protected recovery page. Open it directly only when explicit operator recovery is needed. If an authenticated MCP tool finds no usable Google token, its error includes this safe recovery URL.

Local and recovery CLI

Run this once per Google account you want the server to access:

bash
google-tasks-mcp-bootstrap

Open the printed URL, approve access, and paste the authorization code back into the terminal.

For multiple trusted accounts on one HTTP server, create one stored bearer token per account and bootstrap each account separately:

bash
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

Use each printed bearer token only in the matching account's MCP client. The server stores only bearer-token hashes.

Start The Server

HTTP mode:

bash
python -m google_tasks_mcp --transport http

Health check:

bash
curl http://127.0.0.1:8787/healthz

Expected response:

json
{"ok": true}

Stdio mode:

bash
python -m google_tasks_mcp --transport stdio

Configuration check:

bash
python -m google_tasks_mcp --check

Connect An MCP Client

Remote or local HTTP:

text
URL:  http://127.0.0.1:8787/mcpAuth: Bearer <MCP_BEARER_TOKEN>

For a VPS, replace the URL with your HTTPS endpoint:

text
URL:  https://your-domain.example/mcpAuth: Bearer <MCP_BEARER_TOKEN>

Local stdio:

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

MCP_BEARER_TOKEN is not required for stdio because the MCP client launches the process locally.

Authentication Modes

Bearer-token mode is the default HTTP mode. /mcp requires Authorization: Bearer <token>.

  • MCP_BEARER_TOKEN routes to account default.
  • Tokens created with google-tasks-mcp-create-bearer-token can route different clients to different account_id values.
  • Bearer tokens are displayed once and stored only as hashes.

OAuth 2.0 gateway mode is optional. Enable it when your HTTP MCP client supports OAuth authorization metadata and token refresh.

  • Set MCP_OAUTH_ISSUER, MCP_OAUTH_CLIENT_ID, MCP_OAUTH_CLIENT_SECRET, and MCP_OAUTH_SIGNING_SECRET.
  • Set MCP_OAUTH_RESOURCE to the canonical public MCP URL, or let it default to <issuer>/mcp.
  • Set MCP_OAUTH_REDIRECT_URIS to the callback URI values accepted by your MCP client.
  • Set MCP_OAUTH_ENABLE_DCR=true for clients that use Dynamic Client Registration.
  • The gateway publishes protected-resource and authorization-server metadata, requires PKCE S256, binds tokens to the canonical resource, and includes RFC 9207 issuer identification in authorization redirects.
  • /mcp accepts OAuth-issued access tokens and the legacy bearer token.
  • OAuth client secrets and refresh tokens are stored only by hash. Registered clients and rotating refresh tokens survive restarts when DB_PATH is durable.

The public proxy URL, MCP OAuth issuer/resource, and Google OAuth callback are operator-controlled deployment settings. They may be changed independently. The server does not require a particular hostname or derive these choices from an owner-specific URL.

MCP OAuth authenticates the client to this server. Google OAuth independently authorizes this server to call Google Tasks. The MCP consent flow coordinates the two layers so Connect and Reconnect cannot finish successfully while the configured Google account is knowingly unusable. The standalone operator page remains available for explicit recovery.

Leave MCP_OAUTH_REDIRECT_URIS empty to keep OAuth gateway mode disabled.

Tools

The same 19 tools are available over stdio, bearer-token HTTP, and OAuth gateway HTTP modes. Tools expose standard MCP titles, descriptions, and safety hints where the client supports them.

GroupToolsNotes
Tasklistslist_tasklists, create_tasklist, get_tasklist, update_tasklist, delete_tasklistTasklist delete requires confirm: true; non-empty lists require force: true.
Task readslist_tasks, get_taskRead from one tasklist. If tasklist is omitted, uses DEFAULT_TASKLIST or Google's first list.
Task summariestoday, overdue, upcoming, search, digestIf tasklist is omitted, reads all tasklists and includes tasklist context.
Task mutationsclear_completed, add, complete, update, uncomplete, delete, moveMutate one tasklist/task at a time. clear_completed requires confirm: true.

All tasklist arguments accept a tasklist ID or exact title. Task title lookup is exact after trimming whitespace and ignores case.

For today, overdue, upcoming, search, and digest, omitting tasklist reads every tasklist. Returned task objects include tasklist_id and tasklist_title; digest labels items with tasklist context.

For list_tasks, clear_completed, single-task tools, and write tools, omitting tasklist uses DEFAULT_TASKLIST, or the first list returned by Google. This prevents unqualified writes from touching every list.

Limitations

These are Google Tasks REST API limits:

  • Due dates are date-only. Google drops time-of-day values on task due dates.
  • Recurring tasks cannot be created or read through the Google Tasks REST API.
  • clear_completed hides completed tasks; it does not permanently delete them.

Docker And VPS

Docker:

bash
docker compose up --build

Keep .env, OAuth JSON files, and SQLite databases outside images and public bundles.

VPS/systemd/Caddy templates are in deploy/:

Replace every placeholder domain, path, and user before deploying.

Troubleshooting

Missing bearer token:

  • HTTP /mcp requires Authorization: Bearer <token> unless OAuth gateway mode is handling the client.
  • Stdio mode does not use MCP_BEARER_TOKEN.

Google OAuth app is in Testing mode:

  • Add every bootstrapped Google user as a test user.
  • Testing-mode refresh tokens can expire after 7 days.

Callback URI mismatch:

  • GOOGLE_REDIRECT_URI must exactly match an Authorized redirect URI in Google Cloud.
  • For local web OAuth, use http://127.0.0.1:8787/callback consistently.

Expired or revoked Google refresh token:

  • For hosted HTTP, open GOOGLE_OAUTH_ONBOARDING_URL and reconnect Google.
  • For local or recovery use, run google-tasks-mcp-bootstrap again.
  • For multi-account mode, include the same --account-id you used before.

OAuth MCP client keeps re-authorizing:

  • Ensure the server is running a version with persisted MCP OAuth refresh tokens.
  • Check that DB_PATH points to persistent storage and survives restarts.
  • Verify MCP_OAUTH_ISSUER is the public HTTPS base URL with no trailing slash.
  • Verify MCP_OAUTH_RESOURCE matches the public /mcp URL exactly.
  • On disposable hosts, verify Litestream restored the SQLite replica before startup.

More Docs

Tests

bash
pytest

來源:README.md,提交 4948e10

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包,因此其工具未知。

版本歷史

1
  1. v0.4.0最新Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分