Google Tasks

google-tasks-mcp-server

Um servidor MCP para Google Tasks. Oferece a qualquer cliente MCP (Claude Desktop, Claude Code, Codex, Cursor, etc.) acesso completo de leitura e escrita às suas listas de tarefas e tarefas: listar, criar, atualizar, concluir, excluir e mover, com datas de vencimento reais.

Não existe um servidor MCP oficial do Google Tasks, então este cobre essa lacuna. CRUD completo, fluxo de autenticação OAuth para aplicativos instalados (suas credenciais nunca saem da sua máquina), TypeScript em todo o código.

Ferramentas

Listas de tarefas

• google_tasks_list_tasklists listar todas as listas de tarefas
• google_tasks_get_tasklist obter uma lista de tarefas
• google_tasks_create_tasklist criar uma nova lista de tarefas
• google_tasks_update_tasklist renomear uma lista de tarefas
• google_tasks_delete_tasklist excluir uma lista de tarefas e todas as suas tarefas

Tarefas

• google_tasks_list_tasks listar tarefas em uma lista, com filtros de data de vencimento/atualização e paginação
• google_tasks_get_task obter uma tarefa
• google_tasks_create_task criar uma tarefa (opcionalmente como subtarefa, opcionalmente posicionada)
• google_tasks_update_task atualizar título/notas/data de vencimento/status
• google_tasks_complete_task / google_tasks_reopen_task marcar como concluída / não concluída
• google_tasks_delete_task excluir uma tarefa
• google_tasks_move_task reordenar, alterar o pai ou mover uma tarefa para outra lista
• google_tasks_clear_completed_tasks limpar todas as tarefas concluídas de uma lista

Toda ferramenta suporta response_format: "markdown" | "json".

Início rápido

Pelo npm:

npm install -g @girmmy/google-tasks-mcp-server

Ou nem instale e deixe seu cliente MCP executá-lo via npx (veja o passo 4).

Ou a partir do código-fonte:

git clone https://github.com/girmmy/google-tasks-mcp-server.git
cd google-tasks-mcp-server
npm install
npm run build

De qualquer forma, siga a Configuração abaixo para criar suas próprias credenciais OAuth do Google e autorizar. Não existe versão compartilhada ou hospedada disto; ele fala diretamente com sua própria conta do Google.

Configuração

1. Criar um cliente OAuth do Google Cloud

Cada usuário precisa do seu próprio cliente OAuth. Não é algo que possa ser compartilhado, já que qualquer pessoa usando seu client secret poderia se passar pelo seu aplicativo (embora ainda precisasse do consentimento individual de cada usuário).

1. Acesse o Google Cloud Console, crie (ou escolha) um projeto.
2. APIs & Services → Library → ative a Google Tasks API.
3. APIs & Services → Tela de consentimento OAuth (o Google agora chama isso de "Google Auth Platform"):
   • Tipo de usuário: Externo é suficiente para uso pessoal.
   • Preencha o nome do aplicativo e seu e-mail para suporte/contato.
   • Em Público → Usuários de teste, adicione sua própria conta do Google. Enquanto o aplicativo estiver em status "Testando", apenas usuários de teste listados podem autorizá-lo, o que é suficiente para executar isto você mesmo.
4. Clients → Criar Cliente → Tipo de aplicativo Aplicativo para desktop. Crie-o.
5. Pegue o client ID e o client secret, seja via "Baixar JSON" logo após a criação ou pela página de detalhes do cliente depois. O console do Google não mostrará o texto puro de um secret novamente depois que você navegar para fora; só é possível baixá-lo ou regenerá-lo, então se você o perder, basta adicionar um novo secret em vez de procurar o antigo.
6. Salve esse arquivo. Por padrão, este servidor procura por ele em: ~/.config/google-tasks-mcp-server/client_secret.json (substitua o caminho com a variável de ambiente GOOGLE_TASKS_CLIENT_SECRET, útil se preferir mantê-lo dentro do diretório do projeto, ex.: ./credentials/client_secret.json. credentials/ já está no gitignore.)

O arquivo deve ter esta aparência:

{
  "installed": {
    "client_id": "YOUR_CLIENT_ID.apps.googleusercontent.com",
    "client_secret": "YOUR_CLIENT_SECRET",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token",
    "redirect_uris": ["http://localhost"]
  }
}

2. Instalação

Pelo npm (nada para compilar):

npm install -g @girmmy/google-tasks-mcp-server

A partir do código-fonte:

npm install
npm run build

3. Autorizar (uma única vez)

Se você instalou pelo npm:

google-tasks-mcp-auth
# or without installing anything:
npx -y -p @girmmy/google-tasks-mcp-server google-tasks-mcp-auth

A partir do código-fonte:

npm run auth
# or, if your client secret lives at a custom path:
GOOGLE_TASKS_CLIENT_SECRET=./credentials/client_secret.json npm run auth

Isso imprime uma URL de consentimento do Google e tenta abri-la no seu navegador padrão. Entre, conceda acesso, e ele redireciona de volta para um servidor local de curta duração em http://localhost:53682. O token é armazenado em cache em ~/.config/google-tasks-mcp-server/token.json (substituível com GOOGLE_TASKS_TOKEN_PATH) e renovado automaticamente a partir de então, então você não deve precisar executar isso novamente, a menos que revogue o acesso.

Execute isso na mesma máquina e no mesmo terminal regular que você usará no dia a dia. Veja Solução de Problemas abaixo se estiver executando a partir de um contêiner, VM ou shell isolado onde localhost não mapeia de volta para o seu navegador.

4. Executar

npm start

Ou conecte-o a um cliente MCP. Para Claude Desktop / Claude Code, adicione à sua configuração MCP (geralmente ~/Library/Application Support/Claude/claude_desktop_config.json no macOS).

Usando npm, com seu client secret no caminho padrão ~/.config/..., esta é a configuração completa:

{
  "mcpServers": {
    "google-tasks": {
      "command": "npx",
      "args": ["-y", "@girmmy/google-tasks-mcp-server"]
    }
  }
}

Ou apontando para um checkout do código-fonte:

{
  "mcpServers": {
    "google-tasks": {
      "command": "node",
      "args": ["/absolute/path/to/google-tasks-mcp-server/dist/index.js"],
      "env": {
        "GOOGLE_TASKS_CLIENT_SECRET": "/absolute/path/to/google-tasks-mcp-server/credentials/client_secret.json"
      }
    }
  }
}

Omita o bloco env se você salvou seu client secret no caminho padrão ~/.config/.... Feche e reabra completamente seu cliente MCP depois.

Codex

O Codex usa TOML em vez de JSON. Adicione isto a ~/.codex/config.toml:

[mcp_servers.google-tasks]
command = "npx"
args = ["-y", "@girmmy/google-tasks-mcp-server"]
startup_timeout_sec = 60

Ou deixe a CLI escrever para você:

codex mcp add google-tasks -- npx -y @girmmy/google-tasks-mcp-server

Aumente startup_timeout_sec se o primeiro lançamento expirar. Um npx a frio baixa o pacote antes que o servidor possa responder a initialize, e a tolerância padrão do Codex é curta o suficiente para que isso às vezes falhe apenas na primeira execução.

Se seu client secret não estiver no caminho padrão, adicione:

[mcp_servers.google-tasks.env]
GOOGLE_TASKS_CLIENT_SECRET = "/absolute/path/to/client_secret.json"

Verifique se foi registrado com codex mcp list. A autorização é o mesmo passo único de google-tasks-mcp-auth como em qualquer outro lugar — execute-o em um terminal normal, não dentro do Codex, pois ele precisa abrir um navegador e capturar um redirecionamento de loopback.

Variáveis de ambiente

Variável	Padrão	Finalidade
GOOGLE_TASKS_CLIENT_SECRET	~/.config/google-tasks-mcp-server/client_secret.json	Caminho para o JSON do cliente OAuth baixado
GOOGLE_TASKS_TOKEN_PATH	~/.config/google-tasks-mcp-server/token.json	Caminho onde o token OAuth em cache é armazenado
GOOGLE_TASKS_OAUTH_PORT	53682	Porta de loopback usada apenas durante npm run auth

Notas de segurança

• O client secret e o token em cache são arquivos simples em disco (modo 0600 para o token). Nunca os envie para o controle de versão (.gitignore já exclui client_secret*.json, token.json, credentials/).
• O servidor solicita o escopo completo https://www.googleapis.com/auth/tasks (leitura/escrita). Para acesso somente leitura, edite TASKS_SCOPE em src/constants.ts para .../auth/tasks.readonly antes de executar npm run auth. As ferramentas de escrita falharão então com um 403 do Google, o que é esperado.
• As anotações das ferramentas marcam operações de exclusão/limpeza como destructiveHint: true para que clientes MCP possam avisar ou bloquear com base nelas.
• Nada aqui fala com qualquer servidor além das próprias APIs do Google e, durante npm run auth, um listener de loopback local. Nenhum backend de terceiros envolvido.

Solução de problemas

npm run auth abre uma URL, clico em Permitir, e ele simplesmente trava. O processo executando npm run auth não está na mesma máquina/rede que o navegador onde você está clicando em Permitir. Comum se você estiver executando o servidor dentro de um contêiner, ambiente de desenvolvimento remoto ou shell isolado que isola localhost. Correção: execute npm run auth diretamente em um terminal local normal na máquina cujo navegador você está usando.

Error [TransformError] ... You installed esbuild for another platform Seu node_modules foi instalado em um SO/arquitetura diferente do que você está executando agora, ex.: copiado de um contêiner Docker ou de outra máquina. Correção: rm -rf node_modules package-lock.json && npm install.

Authorization failed: invalid_client Seu client_secret.json tem o client secret errado, geralmente por copiar e colar manualmente em vez de baixá-lo diretamente. Volte ao Google Cloud Console, adicione um novo client secret, baixe ou copie-o diretamente e atualize seu client_secret.json.

O servidor sai imediatamente com "No cached Google Tasks token found" Você ainda não autorizou, ou o fluxo não terminou. Execute google-tasks-mcp-auth (instalação npm) ou npm run auth (checkout do código-fonte) antes de iniciar o servidor.

Desenvolvimento

npm run dev     # run directly from TypeScript with auto-reload
npm run build   # type-check and compile to dist/

Teste com o MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Contribuindo

Issues e PRs são bem-vindos. Isto cobre toda a superfície da Tasks API, mas não foi testado em todos os casos extremos, então se você encontrar um bug ou quiser um recurso, abra uma issue.

Licença

MIT, veja LICENSE.