clear
Clear completed tasks from a Google Tasks task list
LABSCO SUMMARY
Google Tasks with the parts most integrations skip: the hierarchy, the ordering, and more than the first hundred tasks.
The basics are all here; the reasons to choose this one are in the detail. list pages through everything rather than stopping quietly at a hundred, list_with_tree returns the nesting and position order the app shows and a flat list destroys, and move covers indenting, un-indenting and moving between lists rather than only reordering. Setup is the usual Google cost — your own OAuth client and a refresh token — with three different ways to hand it over.
What it is
A Google Tasks server covering more than one list: search and list tasks with full pagination, create, update, move and delete them, and read a list as the tree the Google Tasks interface displays.
What you get
- list_task_lists returns the task lists with their IDs, which every other list-scoped call needs
- list returns tasks from one list or from all of them, paged through rather than silently stopping at the first hundred
- list_with_tree shows one list as its parent-child tree in position order, matching the app, and can include completed or hidden tasks
- search matches on title and notes, scoped to a single list when you want it narrowed
- create takes a title, with optional notes, a due date and a target list
- update patches only the fields you supply — title, notes, due date, status or a link — leaving the rest alone
- move reorders a task, indents it under a parent, un-indents it, or moves it into a different list entirely
- delete removes a single task and clear removes the completed ones from a list
Requirements
Published as @alvincrave/gtasks-mcp and launched over stdio with npx, or built from source. Authentication is your own Google OAuth client with the Tasks scope: GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET and GOOGLE_REFRESH_TOKEN, after enabling the Google Tasks API on a Google Cloud project. Credential files are the alternative — point GTASKS_CREDENTIALS_PATH at the OAuth client JSON and run the auth command once to write GTASKS_TOKEN_PATH — as is a ~/.gtasks-credentials.json holding the same three values. A Docker image can be built from the repository.
Setup effort
One command plus credentials — npx -y @alvincrave/gtasks-mcp, then supply credentials
USE CASES
01
Seeing your lists the way the app shows them
Find the list IDs, then read one back as a tree with the nesting and ordering preserved.
02
Capturing a task out of the conversation
Create it with a title, notes and a due date, in whichever list it belongs to.
03
Finding a task you only half remember
Search across titles and notes, or list everything when the phrasing has gone entirely.
04
Reorganising a list that has drifted
move reorders, nests a task under a parent, pulls it back out, or sends it to a different list.
05
Marking things done and tidying up
Patch the status on the ones that are finished, then clear the completed tasks out of the list.
9 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
create
Create a new task in Google Tasks
delete
Delete a task in Google Tasks
list
List all tasks in Google Tasks
list_task_lists
List all task lists in Google Tasks with their IDs and titles. Use this to discover list IDs before querying specific lists.
list_with_tree
List tasks from a specific task list in tree format (matching Google Tasks UI order). Shows parent-child hierarchy with indentation, sorted by position.
move
Move a task to a new position within its list or to a different list. Can reorder, indent (make subtask), or un-indent.
search
Search for a task in Google Tasks
update
Update a task in Google Tasks
BEFORE YOU INSTALL
What to know first
Tools you get
9 tools when we connected. search, list, create, update, delete, move and clear have no prefix, so they are easy to confuse with another server's tools. clear removes completed tasks from a list.
Requires
- npx on PATH
- GOOGLE_CLIENT_ID in your environment
- GOOGLE_CLIENT_SECRET in your environment
- GOOGLE_REFRESH_TOKEN in your environment
CONTEXT COST
Light Standing cost
Rated by the size of the 9 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
TERMINAL
npx -y @alvincrave/gtasks-mcpMCP Clients
Claude Desktop
CLAUDE DESKTOP · JSON
{
"mcpServers": {
"gtasks": {
"command": "npx",
"args": [
"-y",
"@alvincrave/gtasks-mcp"
],
"env": {
"GOOGLE_CLIENT_ID": "<YOUR_GOOGLE_CLIENT_ID>",
"GOOGLE_CLIENT_SECRET": "<YOUR_GOOGLE_CLIENT_SECRET>",
"GOOGLE_REFRESH_TOKEN": "<YOUR_GOOGLE_REFRESH_TOKEN>"
}
}
}
}Any MCP client — credential files
Build from source, then authenticate once with the OAuth client JSON you downloaded from Google Cloud:
ANY MCP CLIENT — CREDENTIAL FILES · TERMINAL
git clone https://github.com/alvinjchoi/gtasks-mcp.git
cd gtasks-mcp
npm install
npm run build
export GTASKS_CREDENTIALS_PATH=<YOUR_GTASKS_CREDENTIALS_PATH>
export GTASKS_TOKEN_PATH=<YOUR_GTASKS_TOKEN_PATH>
node dist/index.js authThen run the server with the same two variables set, or put gcp-oauth.keys.json in the project root and use the default paths. In a client, that is a server entry that runs node with the full path to dist/index.js in this clone and has GTASKS_CREDENTIALS_PATH and GTASKS_TOKEN_PATH under env.
Any MCP client — home credentials file
Create ~/.gtasks-credentials.json with your own values. The server reads it when GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET and GOOGLE_REFRESH_TOKEN are not set, so the npx block can go in your client without an env section.
ANY MCP CLIENT — HOME CREDENTIALS FILE · JSON
{
"clientId": "<YOUR_CLIENT_ID>",
"clientSecret": "<YOUR_CLIENT_SECRET>",
"refreshToken": "<YOUR_GOOGLE_REFRESH_TOKEN>"
}Any MCP client — Docker
Build the image from a clone of this repository, then run it with your Google credentials:
ANY MCP CLIENT — DOCKER · TERMINAL
git clone https://github.com/alvinjchoi/gtasks-mcp.git
cd gtasks-mcp
docker build -t gtasks-mcp .
docker run -i \
-e GOOGLE_CLIENT_ID=<YOUR_GOOGLE_CLIENT_ID> \
-e GOOGLE_CLIENT_SECRET=<YOUR_GOOGLE_CLIENT_SECRET> \
-e GOOGLE_REFRESH_TOKEN=<YOUR_GOOGLE_REFRESH_TOKEN> \
gtasks-mcpThe container talks MCP over stdin and stdout (docker run -i), so a client uses it by launching that docker run line as the server: docker as the command, the rest of the line as its arguments. The README gives no client entry for Docker; add it in your client's own format.
