google-tasks-local-mcp-server

The Hook

Google Tasks MCP Server is a local Model Context Protocol (MCP) server that provides AI agents with full, granular access to the Google Tasks API. Built using Python and the FastMCP framework, this server enables AI models to manage task lists and tasks, facilitating advanced planning and task organization directly within your AI workflow.

Features Checklist

Tools

The server exposes a comprehensive toolset for full task orchestration:

• Task Lists:

  • list_task_lists: Retrieve all task lists.
  • get_task_list: Get details of a specific list.
  • create_task_list: Create a new task list.
  • update_task_list: Replace an existing task list.
  • patch_task_list: Partially update a task list.
  • delete_task_list: Remove a task list and all its tasks.

• Tasks:

  • list_tasks: List tasks in a list with support for filtering (completed, due dates).
  • get_task: Retrieve detailed information about a single task.
  • create_task: Add a new task with support for hierarchies.
  • update_task: Replace a task.
  • patch_task: Partially update a task (e.g., change status, notes).
  • delete_task: Delete a task.
  • clear_completed_tasks: Hide all completed tasks in a list.
  • move_task: Move a task within a list or between lists, managing parent-child hierarchies.

Architecture

• Protocol: Model Context Protocol (MCP) using STDIO transport.
• Backend: Python 3.10+ with FastMCP.
• API: Google Tasks API.
• Authentication: OAuth 2.0 with PKCE (Installed App Flow).

Quick Start / Installation

Prerequisites

• uv installed on your system.
• A Google Cloud Project with the Google Tasks API enabled.
• OAuth 2.0 Desktop Application credentials.

1. Google Cloud Configuration

1. Create a project in the Google Cloud Console.
2. Enable the Google Tasks API.
3. Configure the OAuth Consent Screen (add yourself as a test user).
4. Create OAuth 2.0 Client IDs for a "Desktop app".
5. Download the client secret JSON or note down the Client ID and Secret.

2. Environment Variables

Set the following variables in your environment or development config:

• GOOGLE_CLIENT_ID: Your Google OAuth Client ID.
• GOOGLE_CLIENT_SECRET: Your Google OAuth Client Secret.

Integration Guide

Google AntiGravity & Claude Desktop Integration

Add the following to your mcp_config.json or claude_desktop_config.json.

{
  "mcpServers": {
    "google-tasks": {
      "command": "uv",
      "args": [
        "run", "-m", "src.mcp_google_tasks.server"
      ],
      "env": {
        "GOOGLE_CLIENT_ID": "YOUR_CLIENT_ID",
        "GOOGLE_CLIENT_SECRET": "YOUR_CLIENT_SECRET"
      },
      "cwd": "/path/to/your/google-tasks-mcp-server"
    }
  }
}

[!NOTE]TOKEN_STORAGE_PATH is no longer required as tokens are stored securely in the system keyring.

SKILL.md

You will find SKILL.md in docs folder. Optimized for "Google Tasks Local MCP Server" usage.

Security

• Local Execution: The server runs locally; your data never passes through third-party servers except Google.
• PKCE: Strengthens the OAuth flow for public clients.
• Secure Storage: Tokens are stored using secure platform-specific mechanisms (Keyring).

Captain & Pilot Context

This project follows an elite design philosophy where the FastMCP core handles the "neural link" between the agent and the API.

• The Orchestrator: Manages the protocol stream and task hierarchies.
• The Specialized Corps: The Google Tasks API serves as the reliable backend engine for persistent storage and global synchronization.

Development & Contribution

Ensure "Immaculate Vibes" by running tests before committing:

# Run pytest
uv run pytest

# Linting and Formatting
uv run ruff check .

Footer & Socials

Created by Brandon Lane "Your README is the storefront of your code. Make it look like a high-end boutique, not a garage sale."

License: MIT