Google Tasks MCP

Gerencie o Google

Documentação

Servidor Google Tasks MCP

Conecte um cliente compatível com MCP ao Google Tasks por meio de um servidor privado que você mesmo executa. O servidor expõe ferramentas compactas para ler, pesquisar, resumir, criar, concluir, atualizar, excluir e mover tarefas do Google Tasks.

Este projeto é para uso auto-hospedado. Você fornece suas próprias credenciais OAuth do Google Cloud, conecta sua própria conta do Google e mantém os tokens em seu próprio banco de dados SQLite.

O Que Você Obtém

19 ferramentas MCP para Google Tasks.
Modo stdio local para configurações de desktop/iniciadas pelo cliente.
Modo HTTP Streamable para hospedagem HTTP local ou VPS.
Autenticação HTTP por token Bearer, além do modo de gateway OAuth 2.0 opcional para clientes MCP que suportam OAuth.
Respostas compactas projetadas para fluxos de trabalho de assistente com baixo contexto.
Roteamento opcional de token Bearer multi-conta gerenciado pelo operador, para configurações conhecidas, como uma conta pessoal e uma conta de trabalho.

Escolha Um Transporte

Caso de uso	Transporte	Autenticação
O cliente MCP inicia o processo diretamente	`stdio`	Nenhum `MCP_BEARER_TOKEN` necessário
Servidor HTTP local	HTTP Streamable em `http://127.0.0.1:8787/mcp`	Token Bearer
VPS ou outro host	HTTP Streamable em `https://your-domain.example/mcp`	Token Bearer ou gateway OAuth

Para orientações mais aprofundadas sobre hospedagem e distribuição, consulte MCP_SERVER_GUIDE.md e DISTRIBUTION.md.

Instalação

git clone https://github.com/ebmurha/google-tasks-mcp.git
cd google-tasks-mcp
python3.11 -m venv .venv
. .venv/bin/activate
pip install -e .
cp .env.example .env

Gere um token Bearer se você for executar o modo HTTP:

python -c "import secrets; print(secrets.token_urlsafe(48))"

Coloque o valor gerado em .env como MCP_BEARER_TOKEN. Não envie .env para o controle de versão.

Configuração do Google Cloud

Crie ou abra um projeto no Google Cloud.
Ative a API Google Tasks.
Configure a tela de consentimento OAuth.
Crie um ID de cliente OAuth 2.0.

Recomendado para HTTP local, VPS, Docker e outras instalações do tipo servidor:

Tipo de aplicativo: Aplicativo web
URI de redirecionamento local: http://127.0.0.1:8787/callback
URI de redirecionamento hospedado: https://your-domain.example/callback
.env: defina GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET e GOOGLE_REDIRECT_URI

Alternativa somente local:

Tipo de aplicativo: Aplicativo para desktop
Baixe o JSON do cliente OAuth fora deste repositório.
Defina GOOGLE_OAUTH_KEYS_PATH para o caminho desse arquivo.
Deixe GOOGLE_CLIENT_ID e GOOGLE_CLIENT_SECRET vazios, a menos que você queira que as variáveis de ambiente substituam o arquivo JSON.

Exemplo de .env para um cliente OAuth web local:

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REDIRECT_URI=http://127.0.0.1:8787/callback
MCP_BEARER_TOKEN=your-generated-token
DB_PATH=./google-tasks.db
BIND_HOST=127.0.0.1
BIND_PORT=8787

Se o aplicativo OAuth do Google estiver no modo Teste, adicione cada conta do Google que você inicializar como usuário de teste, como contas pessoais e de trabalho.

GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET / GOOGLE_OAUTH_KEYS_PATH identificam o aplicativo OAuth do Google Cloud, não a conta de usuário do Google Tasks. Um JSON de cliente OAuth pode ser reutilizado para vários usuários do Google. Cada execução de inicialização armazena um token de atualização separado para a conta do Google que você autoriza no navegador.

Inicializar OAuth do Google

Execute isto uma vez para cada conta do Google à qual você deseja que o servidor acesse:

google-tasks-mcp-bootstrap

Abra a URL impressa, aprove o acesso e cole o código de autorização de volta no terminal.

Para várias contas confiáveis em um único servidor HTTP, crie um token Bearer armazenado por conta e inicialize cada conta separadamente:

google-tasks-mcp-create-bearer-token --account-id personal --label "Personal account"
google-tasks-mcp-bootstrap --account-id personal

google-tasks-mcp-create-bearer-token --account-id work --label "Work account"
google-tasks-mcp-bootstrap --account-id work

Use cada token Bearer impresso apenas no cliente MCP da conta correspondente. O servidor armazena apenas hashes de tokens Bearer.

Iniciar O Servidor

Modo HTTP:

python -m google_tasks_mcp --transport http

Verificação de integridade:

curl http://127.0.0.1:8787/healthz

Resposta esperada:

{"ok": true}

Modo stdio:

python -m google_tasks_mcp --transport stdio

Verificação de configuração:

python -m google_tasks_mcp --check

Conectar Um Cliente MCP

HTTP remoto ou local:

URL:  http://127.0.0.1:8787/mcp
Auth: Bearer <MCP_BEARER_TOKEN>

Para um VPS, substitua a URL pelo seu endpoint HTTPS:

URL:  https://your-domain.example/mcp
Auth: Bearer <MCP_BEARER_TOKEN>

Stdio local:

{
  "command": "/path/to/google-tasks-mcp/.venv/bin/python",
  "args": ["-m", "google_tasks_mcp", "--transport", "stdio"]
}

MCP_BEARER_TOKEN não é necessário para stdio porque o cliente MCP inicia o processo localmente.

Modos de Autenticação

O modo de token Bearer é o modo HTTP padrão. /mcp requer Authorization: Bearer <token>.

MCP_BEARER_TOKEN roteia para a conta default.
Tokens criados com google-tasks-mcp-create-bearer-token podem rotear diferentes clientes para diferentes valores de account_id.
Tokens Bearer são exibidos uma vez e armazenados apenas como hashes.

O modo de gateway OAuth 2.0 é opcional. Ative-o quando seu cliente MCP HTTP suportar metadados de autorização OAuth e atualização de token.

Defina MCP_OAUTH_ISSUER, MCP_OAUTH_CLIENT_ID, MCP_OAUTH_CLIENT_SECRET e MCP_OAUTH_SIGNING_SECRET.
Defina MCP_OAUTH_REDIRECT_URIS para os valores de URI de retorno aceitos pelo seu cliente MCP.
/mcp aceita tokens de acesso emitidos por OAuth e o token Bearer legado.
Os tokens de atualização do gateway OAuth são armazenados por hash e giram no uso, para que os clientes possam se reconectar após a reinicialização do servidor.

Deixe MCP_OAUTH_REDIRECT_URIS vazio para manter o modo de gateway OAuth desativado.

Ferramentas

As mesmas 19 ferramentas estão disponíveis nos modos stdio, HTTP com token Bearer e HTTP com gateway OAuth. As ferramentas expõem títulos, descrições e dicas de segurança padrão do MCP quando o cliente as suporta.

Grupo	Ferramentas	Observações
Listas de tarefas	`list_tasklists`, `create_tasklist`, `get_tasklist`, `update_tasklist`, `delete_tasklist`	A exclusão de lista de tarefas requer `confirm: true`; listas não vazias requerem `force: true`.
Leituras de tarefas	`list_tasks`, `get_task`	Leitura de uma lista de tarefas. Se `tasklist` for omitido, usa `DEFAULT_TASKLIST` ou a primeira lista do Google.
Resumos de tarefas	`today`, `overdue`, `upcoming`, `search`, `digest`	Se `tasklist` for omitido, lê todas as listas de tarefas e inclui o contexto da lista.
Mutações de tarefas	`clear_completed`, `add`, `complete`, `update`, `uncomplete`, `delete`, `move`	Muta uma lista de tarefas/tarefa por vez. `clear_completed` requer `confirm: true`.

Todos os argumentos tasklist aceitam um ID de lista de tarefas ou título exato. A pesquisa por título de tarefa é exata após remover espaços em branco e ignora maiúsculas/minúsculas.

Para today, overdue, upcoming, search e digest, omitir tasklist lê todas as listas de tarefas. Os objetos de tarefa retornados incluem tasklist_id e tasklist_title; digest rotula itens com o contexto da lista de tarefas.

Para list_tasks, clear_completed, ferramentas de tarefa única e ferramentas de escrita, omitir tasklist usa DEFAULT_TASKLIST, ou a primeira lista retornada pelo Google. Isso evita que escritas não qualificadas afetem todas as listas.

Limitações

Estes são limites da API REST do Google Tasks:

As datas de vencimento são apenas de data. O Google descarta valores de hora do dia nas datas de vencimento das tarefas.
Tarefas recorrentes não podem ser criadas ou lidas por meio da API REST do Google Tasks.
clear_completed oculta tarefas concluídas; não as exclui permanentemente.

Docker E VPS

Docker:

docker compose up --build

Mantenha .env, arquivos JSON OAuth e bancos de dados SQLite fora de imagens e pacotes públicos.

Modelos VPS/systemd/Caddy estão em deploy/:

Substitua todo domínio, caminho e usuário de espaço reservado antes de implantar.

Solução de Problemas

Token Bearer ausente:

HTTP /mcp requer Authorization: Bearer <token> a menos que o modo de gateway OAuth esteja lidando com o cliente.
O modo stdio não usa MCP_BEARER_TOKEN.

Aplicativo OAuth do Google no modo Teste:

Adicione cada usuário do Google inicializado como usuário de teste.
Tokens de atualização do modo Teste podem expirar após 7 dias.

Incompatibilidade de URI de retorno:

GOOGLE_REDIRECT_URI deve corresponder exatamente a uma URI de redirecionamento autorizada no Google Cloud.
Para OAuth web local, use http://127.0.0.1:8787/callback de forma consistente.

Token de atualização do Google expirado ou revogado:

Execute google-tasks-mcp-bootstrap novamente para a conta afetada.
Para o modo multi-conta, inclua o mesmo --account-id que você usou antes.

Cliente MCP OAuth reautorizando constantemente:

Garanta que o servidor esteja executando uma versão com tokens de atualização OAuth MCP persistidos.
Verifique se DB_PATH aponta para armazenamento persistente e sobrevive a reinicializações.
Verifique se MCP_OAUTH_ISSUER é a URL base HTTPS pública sem barra final.

Mais Documentação

MCP_SERVER_GUIDE.md explica modelos de hospedagem, limites de credenciais e escolhas entre projeto público vs serviço público.
DISTRIBUTION.md explica publicação em registro, pacote e diretório.
.env.example lista todas as variáveis de ambiente suportadas.
google-tasks-mcp-specifications.md é a fonte de verdade comportamental.

Testes

pytest