Google Tasks MCP Server: Model Context Protocol

Overview

This project implements an MCP (Model Context Protocol) server that synchronizes Google Tasks with systems that consume model context. It acts as a bridge between Google Tasks and LLM-driven applications, exposing task state and metadata using a standardized MCP-style HTTP interface so models and agents can request, update, and consume a user’s task context in a predictable way.

Use cases include letting a chat assistant query your current to‑dos, letting an agent enrich prompts with up‑to‑date task lists, or enabling background processes to push task changes into the model context. The server handles the Google OAuth flow, maps Google Tasks structures into MCP context payloads, and provides endpoints for retrieval and incremental updates so developers can integrate task data without directly managing Google API details.

Features

• Exposes Google Tasks as a Model Context Protocol provider
• Handles OAuth 2.0 authentication and token refresh for Google accounts
• Endpoint(s) for retrieving tasks as MCP-style context blocks
• Incremental sync: supports fetching recent changes since a provided cursor/timestamp
• Configurable persistence and server settings via environment variables
• Lightweight HTTP API suitable for local development, containers, or cloud deployment
• Example client snippets for retrieving and using task context with LLMs

Installation / Configuration

Prerequisites: Git, Docker (optional), and a Google Cloud project with the Tasks API enabled and OAuth credentials (Client ID & Client Secret).

1. Clone the repository

git clone https://github.com/zcaceres/gtasks-mcp.git
cd gtasks-mcp

2. Create a .env file (example)

# .env
GOOGLE_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-google-client-secret
OAUTH_REDIRECT_URI=http://localhost:8080/auth/callback
MCP_BIND_ADDRESS=0.0.0.0:8080
SESSION_SECRET=replace-with-random-secret
# Optional storage / db settings
DATA_DIR=./data

3. Install and run (two common approaches)

• Run with Node.js (if repository is Node-based)

# install dependencies
npm install

# run
npm start

• Run with Docker

# docker-compose.yml (example)
version: '3.7'
services:
  gtasks-mcp:
    image: zcaceres/gtasks-mcp:latest
    ports:
      - "8080:8080"
    environment:
      - GOOGLE_CLIENT_ID=${GOOGLE_CLIENT_ID}
      - GOOGLE_CLIENT_SECRET=${GOOGLE_CLIENT_SECRET}
      - OAUTH_REDIRECT_URI=${OAUTH_REDIRECT_URI}
      - MCP_BIND_ADDRESS=0.0.0.0:8080
    volumes:
      - ./data:/app/data

docker-compose up --build

4. Configure Google OAuth credentials

• In Google Cloud Console: create OAuth 2.0 Client ID, add your redirect URI (e.g. http://localhost:8080/auth/callback).
• Put the Client ID/Secret into your .env or environment.

Environment variables reference:

Available Resources

• GitHub repository (source, issues, examples): https://github.com/zcaceres/gtasks-mcp
• OAuth / Google Tasks API docs: https://developers.google.com/tasks
• Example Postman / curl snippets (included in repo under examples/)
• Local web UI or auth endpoints for authorizing accounts (exposed by the server)

Typical endpoints (implemented by the server)

• GET /auth/authorize — initiate the Google OAuth flow
• GET /auth/callback — receive OAuth code and store tokens
• GET /mcp/context?cursor=… — retrieve MCP-formatted context (task list)
• POST /mcp/sync — accept a cursor or timestamp to return changes since then

(Refer to the repository for exact route names and payload formats.)

Use Cases

1. Enrich conversational agents with current tasks

• Flow: Assistant calls GET /mcp/context for a user, the server returns tasks as context blocks. The assistant includes this context in prompt construction to provide relevant suggestions (e.g., propose scheduling, summarize overdue tasks).

Example curl to retrieve context:

curl -H "Authorization: Bearer <session-token>" "http://localhost:8080/mcp/context?limit=50"

2. Agent-driven task creation and updates

• An LLM-based agent decides to create or update an item. It issues a request to the MCP server (or a companion endpoint) which performs the corresponding Google Tasks API call on behalf of the user.

3. Background sync for context-aware pipelines

• A pipeline polls /mcp/sync with a cursor/timestamp to receive only new or changed tasks. This reduces redundant data transfer and keeps model context fresh for periodic summarization or notification generation.

4. Personalization and prompt priming

• Use task metadata (due dates, completed status, priorities) to prime prompts for deadline-aware planning, daily standup summaries, or to build persistent context that influences model responses.

Notes for Developers

• Secure the auth endpoints and tokens carefully. The server will store OAuth tokens needed to access Google Tasks; treat the DATA_DIR as sensitive.
• Test locally with a single Google account before deploying to multi-user scenarios. The included examples demonstrate the OAuth flow and how tasks map into the MCP payload shape.
• Consult the repo’s examples/ directory and the repo README for exact payload schemas and client helper code.

This MCP server provides a focused integration point for adding Google Tasks into model-driven workflows, letting developers concentrate on how to use task context rather than managing Google API mechanics.