<div align="center">
  <img src="docs/img/logotype.png" alt="Google Tasks MCP Server Banner" width="450">
  
  [![Build](https://img.shields.io/badge/build-passing-brightgreen)](#)
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  [![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
  [![MCP](https://img.shields.io/badge/MCP-Protocol-orange)](https://modelcontextprotocol.io/)

  **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](https://github.com/jlowin/fastmcp).
- **API**: [Google Tasks API](https://developers.google.com/workspace/tasks).
- **Authentication**: OAuth 2.0 with PKCE (Installed App Flow).

---

## <img src="docs/img/logo.png" width="35" height="35"> Quick Start / Installation

### Prerequisites
- [uv](https://github.com/astral-sh/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`. 

```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:
```bash
# 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](https://brandonlane.xyz) |
| **Facebook** | [Brandon Lane](https://facebook.com/brandon.lane) |
| **Instagram** | [@brandon.lane.xyz](https://instagram.com/brandon.lane.xyz) |
| **Messenger** | [Chat with me](https://m.me/brandon.lane) |

---
**License**: MIT