Google Tasks MCP Server

A comprehensive Model Context Protocol (MCP) server for Google Tasks that enables LLMs to manage tasks and task lists through well-designed, workflow-oriented tools.

Features

This MCP server provides intelligent, workflow-oriented tools for Google Tasks management:

Task List Management

• Create, update, delete, and list task lists
• Organize tasks into projects and categories

Task Operations

• Create tasks with titles, notes, due dates, and hierarchical structure (subtasks)
• List tasks with powerful filtering (date ranges, status, pagination)
• Update tasks - modify title, notes, status, due dates
• Delete tasks permanently
• Move tasks between positions and parents
• Clear completed tasks in bulk

Workflow Tools

• Quick Add - Natural language task creation
• Bulk Create - Create multiple tasks at once
• Search Tasks - Find tasks across all lists
• Task Summary - Get organized views by time range (today, tomorrow, week, overdue)

Prerequisites

1. Python 3.8+ installed on your system
2. Google Cloud Project with Tasks API enabled
3. OAuth 2.0 Credentials for desktop application

Setup Instructions

Step 1: Google Cloud Setup

1. Go to Google Cloud Console

2. Create a new project or select an existing one

3. Enable the Google Tasks API:

   • Go to "APIs & Services" > "Library"
   • Search for "Tasks API"
   • Click "Enable"

4. Create OAuth 2.0 Credentials:

   • Go to "APIs & Services" > "Credentials"
   • Click "Create Credentials" > "OAuth client ID"
   • Choose "Desktop app" as the application type
   • Give it a name (e.g., "Google Tasks MCP")
   • Download the credentials JSON file

5. Create the configuration directory:

   mkdir -p ~/.google_tasks_mcp
   

6. Save the downloaded credentials file as:

   ~/.google_tasks_mcp/credentials.json
   

Step 2: Install Dependencies

pip install -r requirements.txt

Step 3: First Run & Authentication

Run the server for the first time to authenticate:

python google_tasks_mcp.py

This will:

1. Open a browser window for Google authentication
2. Ask you to authorize the application
3. Save the authentication token for future use

Configuration

For Claude Desktop App

Add this to your Claude desktop configuration file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "google-tasks": {
      "command": "python",
      "args": ["/path/to/google_tasks_mcp.py"],
      "env": {}
    }
  }
}

Replace /path/to/google_tasks_mcp.py with the actual path to the server file.

For Other MCP Clients

The server runs on stdio transport by default:

python google_tasks_mcp.py

Running as a Remote (HTTP/SSE) MCP Server

This server can also run remotely over HTTP/SSE. Control it with environment variables:

• MCP_MODE: set to remote (enables HTTP/SSE). Default: stdio.
• MCP_HOST: bind host (e.g., 0.0.0.0). Default: 0.0.0.0.
• MCP_PORT: port number. Default: 8000.
• MCP_PATH: SSE endpoint path. Default: /sse.

Example:

source /Users/omshejul/python-env/venv/bin/python

export MCP_MODE=remote
export MCP_HOST=0.0.0.0
export MCP_PORT=8000
export MCP_PATH=/sse
python google_tasks_mcp.py

Claude Remote Config (SSE)

Claude Desktop typically expects stdio servers. Use the mcp-remote adapter to connect via SSE. Add an entry like this to the mcpServers section of your Claude config:

{
  "mcpServers": {
    "google-tasks": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "http://YOUR_HOST:8000/sse"]
    }
  }
}

Replace YOUR_HOST and port as needed. Ensure the server is reachable from the client.

Optional: Require a Bearer Token

Set an auth token for the remote server so clients must present Authorization: Bearer <token>:

export MCP_AUTH_TOKEN=REPLACE_ME_SECRET
export MCP_MODE=remote
export MCP_HOST=0.0.0.0
export MCP_PORT=8000
export MCP_PATH=/sse
/Users/omshejul/python-env/venv/bin/python google_tasks_mcp.py

For Claude with mcp-remote, pass the header and keep the secret in an env var:

{
  "mcpServers": {
    "google-tasks": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "http://YOUR_HOST:8000/sse",
        "--header",
        "Authorization:Bearer ${GOOGLE_TASKS_MCP_TOKEN}"
      ],
      "env": {
        "GOOGLE_TASKS_MCP_TOKEN": "REPLACE_ME_SECRET"
      }
    }
  }
}

Available Tools

Task List Management

create_task_list

Create a new task list for organizing related tasks.

Input: title (string)
Returns: Created task list details

list_task_lists

List all task lists with pagination support.

Input:
- max_results (1-50, default: 20)
- page_token (optional)
- response_format (json/markdown/concise/detailed)
Returns: List of task lists

update_task_list

Rename an existing task list.

Input:
- tasklist_id (string)
- title (string)
Returns: Updated task list

delete_task_list

⚠️ Permanently delete a task list and all its tasks.

Input: tasklist_id (string)
Returns: Confirmation

Task Operations

create_task

Create a new task with optional details.

Input:
- title (string, required)
- notes (string, optional)
- due_date (ISO format YYYY-MM-DD, optional)
- tasklist_id (default: "@default")
- parent_task_id (optional, for subtasks)
Returns: Created task details

list_tasks

List tasks with comprehensive filtering options.

Input:
- tasklist_id (default: "@default")
- max_results (1-100, default: 30)
- show_completed (boolean, default: false)
- show_deleted (boolean, default: false)
- due_min/due_max (ISO dates for filtering)
- completed_min/completed_max (ISO dates)
- page_token (for pagination)
- response_format (json/markdown/concise/detailed)
Returns: Filtered task list

update_task

Modify task properties.

Input:
- task_id (string, required)
- tasklist_id (default: "@default")
- title (optional)
- notes (optional)
- status (needsAction/completed, optional)
- due_date (ISO format or "clear", optional)
Returns: Updated task

delete_task

⚠️ Permanently delete a task.

Input:
- task_id (string)
- tasklist_id (default: "@default")
Returns: Confirmation

move_task

Reorganize task position or hierarchy.

Input:
- task_id (string)
- tasklist_id (default: "@default")
- parent_task_id (optional)
- previous_task_id (optional)
Returns: Moved task details

clear_completed_tasks

⚠️ Remove all completed tasks from a list.

Input:
- tasklist_id (default: "@default")
Returns: Confirmation

Workflow Tools

quick_add_task

Create tasks using natural language.

Input:
- text (string, e.g., "Buy milk tomorrow")
- tasklist_id (default: "@default")
Returns: Created task

Examples:

• "Meeting with John tomorrow"
• "Urgent: Fix login bug"
• "Submit report next week"

bulk_create_tasks

Create multiple tasks at once.

Input:
- tasks (list of strings, 1-50 items)
- tasklist_id (default: "@default")
- due_date (optional, applies to all)
Returns: Creation summary

search_tasks

Find tasks across all task lists.

Input:
- query (string)
- include_completed (boolean, default: false)
- max_results (1-50, default: 20)
- response_format (json/markdown/concise/detailed)
Returns: Matching tasks from all lists

get_task_summary

Get organized task overview by time range.

Input:
- time_range (today/tomorrow/week/overdue/all)
- include_completed (boolean, default: false)
- response_format (concise/markdown/detailed)
Returns: Task summary for time period

Usage Examples

Daily Planning Workflow

1. "Get my task summary for today"
2. "Show me overdue tasks"
3. "Create task 'Review quarterly report' due tomorrow"
4. "Mark task [ID] as completed"

Project Setup Workflow

1. "Create a task list called 'Website Redesign'"
2. "Bulk create tasks: ['Design mockups', 'Get client feedback', 'Implement changes', 'Testing', 'Deploy']"
3. "Set due date 2024-02-15 for all tasks"

Task Search Workflow

1. "Search for tasks containing 'meeting'"
2. "Find all tasks with 'urgent' in the title"
3. "Show completed tasks from last week"

Response Formats

The server supports multiple response formats:

• JSON: Raw API response for processing
• Markdown: Formatted for readability
• Concise: Minimal information for quick viewing
• Detailed: Complete task information including IDs

Error Handling

The server provides clear, actionable error messages:

• Authentication errors with setup instructions
• Invalid input with specific guidance
• API errors with suggested fixes
• Rate limiting information when applicable

Security

• OAuth 2.0 tokens are stored locally in ~/.google_tasks_mcp/token.json
• Credentials never leave your local machine
• Token refresh is handled automatically
• Scoped access only to Google Tasks

Troubleshooting

Authentication Issues

• Ensure credentials.json is in the correct location
• Delete token.json to re-authenticate
• Check that Tasks API is enabled in Google Cloud Console

Permission Errors

• Verify the Google account has access to Google Tasks
• Check OAuth consent screen is configured
• Ensure correct scopes are authorized

Connection Issues

• Verify internet connectivity
• Check firewall settings
• Ensure Google services are accessible

Development

Adding New Tools

1. Define Pydantic model for input validation
2. Implement tool function with @mcp.tool decorator
3. Add comprehensive docstring and error handling
4. Update README documentation

Testing

Run the server in development mode:

python google_tasks_mcp.py --debug

License

MIT License - See LICENSE file for details

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

Support

For issues or questions:

1. Check the troubleshooting section
2. Review Google Tasks API documentation
3. Open an issue with detailed error information

Acknowledgments

Built with:

• FastMCP - MCP framework
• Google Tasks API - Task management
• Model Context Protocol - LLM integration standard