Google-Tasks-Local-MCP-Server

<div align="center"> <img src="docs/img/logotype.png" alt="Google Tasks MCP Server Banner" width="450">

Full-spectrum Google Tasks integration for AI agents and elite capsuleers. </div>

---

<img src="docs/img/logo.png" width="35" height="35"> 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.

---

<img src="docs/img/logo.png" width="35" height="35"> Features Checklist

<img src="docs/img/logo.png" width="35" height="35"> 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.

<img src="docs/img/poster.png" width="100%">

---

<img src="docs/img/logo.png" width="35" height="35"> 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).

---

<img src="docs/img/logo.png" width="35" height="35"> 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.

---

<img src="docs/img/logo.png" width="35" height="35"> 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.

<img src="docs/img/logo.png" width="35" height="35"> SKILL.md

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

---

<img src="docs/img/logo.png" width="35" height="35"> 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).

---

<img src="docs/img/logo.png" width="35" height="35"> 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.

---

<img src="docs/img/logo.png" width="35" height="35"> Development & Contribution

Ensure "Immaculate Vibes" by running tests before committing:

# Run pytest
uv run pytest

# Linting and Formatting
uv run ruff check .

---

<img src="docs/img/logo.png" width="35" height="35"> 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."

Platform	Link
Website	brandonlane.xyz
Facebook	Brandon Lane
Instagram	@brandon.lane.xyz
Messenger	Chat with me

---

License: MIT