What is this?

Seamless MCP integration for Google Tasks — create, search, update, and delete tasks directly from Claude or other MCP clients. OAuth 2.0 authenticated, with full CRUD operations and resource URI support.

✨ Features

| Feature | Details | |---------|---------| | Create Tasks | Add new tasks with title, notes, and due dates | | Search & Filter | Full-text search across all tasks | | List Management | View all tasks with cursor-based pagination | | Update Tasks | Modify title, notes, status, and due dates | | Task Deletion | Remove individual tasks or clear completed items | | List Operations | List task lists to get IDs for task operations | | OAuth 2.0 | Secure Google account authentication | | Resource API | Access tasks via gtasks:///<task_id> URIs |

🚀 Quick Start

1. Create a Google Cloud project and enable the Google Tasks API
2. Set up OAuth credentials (Desktop App type)
3. Place credentials in gcp-oauth.keys.json
4. Run authentication: npm run start auth
5. Build and configure: npm run build, then add to your MCP config

📦 Installation

Via Smithery (Recommended)

npx -y @smithery/cli install @zcaceres/gtasks --client claude

Manual Setup

git clone https://github.com/sudohakan/gtasks-mcp.git
cd gtasks-mcp
npm install
npm run build

🔧 Configuration

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "gtasks": {
      "command": "node",
      "args": ["/path/to/gtasks-mcp/dist/index.js"]
    }
  }
}

🔐 Authentication

Run the authentication flow once to save your Google credentials:

npm run start auth

This will:

1. Open your default browser to Google's OAuth login
2. Request permission to access Google Tasks
3. Save credentials to .gtasks-server-credentials.json

Subsequent server runs will use the saved credentials.

🛠️ Development

| Command | Purpose | |---------|---------| | npm run build | Build for production (TypeScript → JavaScript) | | npm run dev | Watch mode for development | | npm run start | Run the server | | npm run start auth | Run authentication flow | | npm test | Run test suite |

📚 Available Tools

search

Search for tasks using a query string.

Input:

• query (string, required): Search terms

Output: Matching tasks with full details

list

List all tasks across all task lists.

Input:

• cursor (string, optional): Pagination cursor

Output: Array of tasks with metadata

list-tasklists

List all task lists in your Google Tasks account.

Output: Array of task list IDs and names

create

Create a new task.

Input:

• taskListId (string, optional): Target task list (uses default if omitted)
• title (string, required): Task title
• notes (string, optional): Task description
• due (string, optional): Due date (ISO 8601 format)

Output: Created task with ID and metadata

update

Update an existing task.

Input:

• taskListId (string, optional): Task list containing the task
• id (string, required): Task ID to update
• uri (string, required): Task URI
• title (string, optional): New title
• notes (string, optional): New notes
• status (string, optional): New status (needsAction or completed)
• due (string, optional): New due date

Output: Updated task details

delete

Delete a task.

Input:

• taskListId (string, required): Task list containing the task
• id (string, required): Task ID to delete

Output: Confirmation of deletion

clear

Clear all completed tasks from a task list.

Input:

• taskListId (string, required): Target task list

Output: Confirmation of cleared tasks

🏗️ Architecture

This MCP server implements the Model Context Protocol to expose Google Tasks as a resource and tool interface:

• Resources: Tasks accessible via gtasks:///<task_id> URIs
• Tools: CRUD operations, search, and list management
• Auth: OAuth 2.0 with local credential storage
• Transport: HTTP-based MCP protocol

📁 Project Structure

gtasks-mcp/
├── src/
│   └── index.ts           # Main server implementation
├── dist/                  # Compiled output
├── package.json           # Dependencies and scripts
├── tsconfig.json          # TypeScript configuration
├── README.md              # This file
├── LICENSE                # MIT License
├── CHANGELOG.md           # Version history
├── SECURITY.md            # Security policy
├── CONTRIBUTING.md        # Development guidelines
└── CODE_OF_CONDUCT.md     # Community standards

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for setup instructions, code standards, and the pull request process.

📄 License

MIT — Copyright © 2026 Hakan Topçu