Google Tasks

Servidor MCP do Google Tasks

Um servidor Model Context Protocol (MCP) para Google Tasks. Gerencie listas de tarefas e tarefas por meio de linguagem natural no Claude Desktop e outros clientes MCP.

Bifurcado de zcaceres/gtasks-mcp com opções de autenticação mais robustas, suporte a múltiplas listas, paginação e ferramentas de hierarquia.

Nome no registro: io.github.alvinjchoi/gtasks-mcp
npm: @alvincrave/gtasks-mcp

Recursos

• Liste e pesquise tarefas (opcionalmente limitado a uma lista de tarefas)
• Pagine por todas as tarefas (sem limite silencioso de 100 tarefas)
• Crie, atualize, exclua e limpe tarefas concluídas
• Descubra listas de tarefas (list_task_lists)
• Visualize hierarquia pai/filho (list_with_tree)
• Reordene, aninhe ou mova tarefas entre listas (move)
• Autenticação OAuth2 via variáveis de ambiente, arquivos de credenciais ou auth interativo
• Suporte a Docker

Instalação

Recomendado (Claude Desktop / qualquer cliente MCP) — executa o pacote npm publicado mais recente:

npx -y @alvincrave/gtasks-mcp

Ou instale globalmente:

npm install -g @alvincrave/gtasks-mcp

A partir do código-fonte

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

Configuração

Opção A — Variáveis de ambiente (Claude Desktop)

1. Crie um projeto no Google Cloud e ative a API Google Tasks.
2. Crie credenciais OAuth 2.0 para Desktop e obtenha um token de atualização (o OAuth Playground com escopo https://www.googleapis.com/auth/tasks funciona).
3. Configure o Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json no macOS):

{
  "mcpServers": {
    "gtasks": {
      "command": "npx",
      "args": ["-y", "@alvincrave/gtasks-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your_client_id_here",
        "GOOGLE_CLIENT_SECRET": "your_client_secret_here",
        "GOOGLE_REFRESH_TOKEN": "your_refresh_token_here"
      }
    }
  }
}

Opção B — Arquivos de credenciais (local / compartilhado com outros servidores MCP do Google)

1. Baixe seu JSON de cliente OAuth (gcp-oauth.keys.json).
2. Autentique uma vez:

export GTASKS_CREDENTIALS_PATH=/path/to/gcp-oauth.keys.json
export GTASKS_TOKEN_PATH=/path/to/.gtasks-server-credentials.json
node dist/index.js auth

3. Execute o servidor com as mesmas variáveis de ambiente definidas (ou coloque gcp-oauth.keys.json na raiz do projeto e use os padrões).

Aliases também aceitos:

Finalidade	Preferido	Alias
Chaves do cliente OAuth	GTASKS_CREDENTIALS_PATH	GOOGLE_OAUTH_KEYS_PATH
Tokens salvos	GTASKS_TOKEN_PATH	GOOGLE_TASKS_CREDENTIALS_PATH

Opção C — Arquivo de configuração no diretório pessoal

Crie ~/.gtasks-credentials.json:

{
  "clientId": "your_client_id",
  "clientSecret": "your_client_secret",
  "refreshToken": "your_refresh_token"
}

Ferramentas

Ferramenta	Descrição
search	Pesquise tarefas por título/notas. taskListId opcional.
list	Liste tarefas (todas as listas, ou uma via taskListId). Totalmente paginado.
list_task_lists	Liste nomes e IDs das listas de tarefas.
list_with_tree	Visualização em árvore para uma lista (pai/filho, ordem de posição).
move	Reordene, aninhe/desaninde ou mova entre listas.
create	Crie uma tarefa (title obrigatório; notas/data/taskListId opcionais).
update	Atualize parcialmente uma tarefa (apenas os campos fornecidos são alterados).
delete	Exclua uma tarefa.
clear	Limpe tarefas concluídas de uma lista.

Exemplos de uso

show my task lists
list tasks in list <id>
search for tasks containing "meeting"
create a task named "Prepare presentation" due 2026-07-20
show the task tree for list <id>
move task <id> under parent <parentId>
mark task <id> completed

Docker

docker build -t gtasks-mcp .
docker run -i \
  -e GOOGLE_CLIENT_ID=your_client_id \
  -e GOOGLE_CLIENT_SECRET=your_client_secret \
  -e GOOGLE_REFRESH_TOKEN=your_refresh_token \
  gtasks-mcp

Desenvolvimento

npm install
npm run build
npm start

Verificação de autenticação / login interativo:

npm run build
node dist/index.js auth

Notas de Segurança

• Trate tokens de atualização como senhas
• Prefira variáveis de ambiente ou arquivos de credenciais ignorados — nunca os envie para o repositório
• Gire as credenciais se vazarem

Contribuidores

• ArtyMcLabin — paginação, filtragem taskListId, list_task_lists, list_with_tree, move e autenticação baseada em arquivos (#1)
• zcaceres — servidor MCP original do Google Tasks
• alvinjchoi — manutenção do fork, empacotamento Smithery/npm

Veja CONTRIBUTORS.md.

Licença

MIT