Google Tasks MCP Server

1# Google Tasks MCP Server
2 
3This Model Context Protocol (MCP) server provides a bridge between Claude and Google Tasks, allowing you to manage your task lists and tasks directly through Claude.
4 
5> [!NOTE]
6> All (bar some edits) code in this project was ["vibe coded"](https://en.wikipedia.org/wiki/Vibe_coding) - generated with Claude/Copilot with instructions from me.
7 
8## Features
9 
10This MCP server provides the following functionality:
11 
12### Task List Management
13- `list-tasklists` - List all your task lists
14- `get-tasklist` - Get details about a specific task list
15- `create-tasklist` - Create a new task list
16- `update-tasklist` - Update an existing task list
17- `delete-tasklist` - Delete a task list
18 
19### Task Management
20- `list-tasks` - List all tasks in a task list
21- `get-task` - Get details about a specific task
22- `create-task` - Create a new task
23- `update-task` - Update an existing task
24- `delete-task` - Delete a task
25- `complete-task` - Mark a task as completed
26- `move-task` - Move a task (reorder or change parent)
27- `clear-completed-tasks` - Clear all completed tasks from a list
28 
29## Setup Instructions
30 
31### 1. Create Google Cloud Project & Enable API
32 
331. Go to the [Google Cloud Console](https://console.cloud.google.com/)
342. Create a new project
353. Navigate to "APIs & Services" > "Library"
364. Search for "Google Tasks API" and enable it
375. Go to "APIs & Services" > "Credentials"
386. Click "Create Credentials" > "OAuth Client ID"
397. Configure the OAuth consent screen (External is fine for personal use)
408. For Application Type, select "Web application"
419. Add "http://localhost:3000/oauth2callback" as an authorized redirect URI
4210. Create the client ID and secret
43 
44### 2. Configure Claude for Desktop
45 
461. Install [Claude for Desktop](https://claude.ai/download)
472. Open the Claude configuration file:
48   - MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
49   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
503. Add the Google Tasks MCP server configuration:
51 
52```json
53{
54  "mcpServers": {
55    "google-tasks": {
56      "command": "node",
57      "args": ["/path/to/google-tasks-mcp/build/index.js"],
58      "env": {
59        "GOOGLE_CLIENT_ID": "your_client_id_here",
60        "GOOGLE_CLIENT_SECRET": "your_client_secret_here",
61        "GOOGLE_REDIRECT_URI": "http://localhost:3000/oauth2callback"
62      }
63    }
64  }
65}
66```
67 
68Replace the path and credentials with your own values.
69 
70**Environment Variables:**
71- `GOOGLE_CLIENT_ID` (required) - Your Google OAuth Client ID
72- `GOOGLE_CLIENT_SECRET` (required) - Your Google OAuth Client Secret  
73- `GOOGLE_REDIRECT_URI` (optional) - OAuth redirect URI (defaults to `http://localhost:3000/oauth2callback`)
74 
75**Note:** The server validates that `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` are set at startup and will fail with clear error messages if they are missing or invalid.
76 
77### 3. Build and Run the Server
78 
791. Install dependencies:
80```bash
81npm install
82```
83 
842. Build the server:
85```bash
86npm run build
87```
88 
893. Restart Claude for Desktop
90 
91## Authentication Flow
92 
93When you first use the Google Tasks MCP server:
94 
951. Use the `authenticate` tool to get an authorization URL
962. Visit the URL in your browser and sign in with your Google account
973. After authorizing, you'll receive a code on the browser page
984. Use the `set-auth-code` tool with this code to complete authentication
995. You can now use all other tools to interact with Google Tasks
100 
101**Note:** Your authentication tokens (including refresh tokens) are automatically saved to disk at `~/.config/google-tasks-mcp/credentials.json` with restricted permissions (600). This means:
102- **You only need to authenticate once** - credentials persist across server restarts
103- **Automatic token refresh** - Access tokens are automatically refreshed when they expire (typically after 1 hour) using the saved refresh token
104- **No re-authentication needed** - After the initial setup, you won't need to authenticate again unless you revoke access or delete the credentials file
105 
106## Requirements
107 
108- Node.js 20+ (see `package.json` engines)
109- Claude for Desktop (latest version)
110- Google Cloud Project with Tasks API enabled
111 
112## Implementation Features
113 
114This MCP server includes the following improvements:
115- **Persistent token storage** - Authentication credentials are saved to disk (`~/.config/google-tasks-mcp/credentials.json`) with restricted permissions, so you only need to authenticate once
116- **Environment variable validation** - Startup validation ensures required credentials are configured with clear error messages
117- **Automatic token refresh** - OAuth tokens are automatically refreshed when they expire, eliminating the need to re-authenticate during active sessions or after restarts
118- **Enhanced input validation** - Comprehensive validation of all inputs including ID formats, string lengths, and RFC 3339 date formats
119- **HTML sanitization** - OAuth callback responses are sanitized to prevent XSS vulnerabilities
120- **Graceful shutdown** - Proper cleanup of resources on SIGINT/SIGTERM signals
121- **Type safety** - Full TypeScript type safety throughout the codebase with proper interfaces
122- **Configurable redirect URI** - The OAuth redirect URI can be customized via the `GOOGLE_REDIRECT_URI` environment variable
123 
124## Screenshots
125 
126### Claude Desktop
127![Claude Desktop Screenshot](./assets/claude.png)
128 
129### Cursor
130![Cursor Screenshot](./assets/cursor.png)
131 
132## License
133 
134This project is for demonstration purposes only. Use at your own risk.
135