Google Tasks MCP

Gestiona Google Tasks desde tu asistente de IA usando lenguaje natural.

Documentación

Servidor Google Tasks MCP

Conecta un cliente compatible con MCP a Google Tasks a través de un servidor privado que tú mismo ejecutas. El servidor expone herramientas compactas para leer, buscar, resumir, crear, completar, actualizar, eliminar y mover tareas de Google Tasks.

Este proyecto es para uso autoalojado. Tú proporcionas tus propias credenciales OAuth de Google Cloud, conectas tu propia cuenta de Google y mantienes los tokens en tu propia base de datos SQLite.

Lo Que Obtienes

19 herramientas MCP para Google Tasks.
Modo stdio local para configuraciones de escritorio o iniciadas por el cliente.
Modo HTTP transmisible para alojamiento HTTP local o VPS.
Autenticación HTTP con token portador, más modo de puerta de enlace OAuth 2.0 opcional para clientes MCP que admiten OAuth.
Respuestas compactas diseñadas para flujos de trabajo de asistente con bajo contexto.
Enrutamiento opcional de tokens portadores multi-cuenta gestionado por el operador, para configuraciones habituales como una cuenta personal y una cuenta de trabajo.

Elige Un Transporte

Caso de uso	Transporte	Autenticación
El cliente MCP inicia el proceso directamente	`stdio`	No se necesita `MCP_BEARER_TOKEN`
Servidor HTTP local	HTTP transmisible en `http://127.0.0.1:8787/mcp`	Token portador
VPS u otro host	HTTP transmisible en `https://your-domain.example/mcp`	Token portador o puerta de enlace OAuth

Para obtener orientación más detallada sobre alojamiento y distribución, consulta MCP_SERVER_GUIDE.md y DISTRIBUTION.md.

Instalación

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

Genera un token portador si vas a ejecutar el modo HTTP:

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

Coloca el valor generado en .env como MCP_BEARER_TOKEN. No confirmes .env.

Configuración De Google Cloud

Crea o abre un proyecto de Google Cloud.
Habilita la API de Google Tasks.
Configura la pantalla de consentimiento OAuth.
Crea un ID de cliente OAuth 2.0.

Recomendado para HTTP local, VPS, Docker y otras instalaciones tipo servidor:

Tipo de aplicación: Aplicación web
URI de redirección local: http://127.0.0.1:8787/callback
URI de redirección alojada: https://your-domain.example/callback
.env: establece GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET y GOOGLE_REDIRECT_URI

Alternativa solo local:

Tipo de aplicación: Aplicación de escritorio
Descarga el JSON del cliente OAuth fuera de este repositorio.
Establece GOOGLE_OAUTH_KEYS_PATH a esa ruta de archivo.
Deja GOOGLE_CLIENT_ID y GOOGLE_CLIENT_SECRET vacíos a menos que quieras que las variables de entorno anulen el archivo JSON.

Ejemplo de .env para un 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

Si la aplicación OAuth de Google está en modo Prueba, añade cada cuenta de Google que inicialices como usuario de prueba, como cuentas personales y de trabajo.

GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET / GOOGLE_OAUTH_KEYS_PATH identifican la aplicación OAuth de Google Cloud, no la cuenta de usuario de Google Tasks. Un JSON de cliente OAuth puede reutilizarse para varios usuarios de Google. Cada ejecución de inicialización almacena un token de actualización separado para la cuenta de Google que autorizas en el navegador.

Inicialización De Google OAuth

Ejecuta esto una vez por cada cuenta de Google a la que quieras que el servidor acceda:

google-tasks-mcp-bootstrap

Abre la URL impresa, aprueba el acceso y pega el código de autorización de vuelta en la terminal.

Para múltiples cuentas de confianza en un solo servidor HTTP, crea un token portador almacenado por cuenta e inicializa cada cuenta por separado:

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

Usa cada token portador impreso solo en el cliente MCP de la cuenta correspondiente. El servidor almacena solo hashes de tokens portadores.

Inicia El Servidor

Modo HTTP:

python -m google_tasks_mcp --transport http

Verificación de salud:

curl http://127.0.0.1:8787/healthz

Respuesta esperada:

{"ok": true}

Modo stdio:

python -m google_tasks_mcp --transport stdio

Verificación de configuración:

python -m google_tasks_mcp --check

Conecta Un Cliente MCP

HTTP remoto o local:

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

Para un VPS, reemplaza la URL con tu 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 no es necesario para stdio porque el cliente MCP inicia el proceso localmente.

Modos De Autenticación

El modo de token portador es el modo HTTP predeterminado. /mcp requiere Authorization: Bearer <token>.

MCP_BEARER_TOKEN enruta a la cuenta default.
Los tokens creados con google-tasks-mcp-create-bearer-token pueden enrutar diferentes clientes a diferentes valores de account_id.
Los tokens portadores se muestran una vez y se almacenan solo como hashes.

El modo de puerta de enlace OAuth 2.0 es opcional. Actívalo cuando tu cliente MCP HTTP admita metadatos de autorización OAuth y actualización de tokens.

Establece MCP_OAUTH_ISSUER, MCP_OAUTH_CLIENT_ID, MCP_OAUTH_CLIENT_SECRET y MCP_OAUTH_SIGNING_SECRET.
Establece MCP_OAUTH_REDIRECT_URIS a los valores de URI de devolución de llamada aceptados por tu cliente MCP.
/mcp acepta tokens de acceso emitidos por OAuth y el token portador heredado.
Los tokens de actualización de la puerta de enlace OAuth se almacenan por hash y rotan al usarse, para que los clientes puedan reconectarse después de reiniciar el servidor.

Deja MCP_OAUTH_REDIRECT_URIS vacío para mantener el modo de puerta de enlace OAuth deshabilitado.

Herramientas

Las mismas 19 herramientas están disponibles en los modos stdio, HTTP con token portador y HTTP con puerta de enlace OAuth. Las herramientas exponen títulos estándar de MCP, descripciones y sugerencias de seguridad donde el cliente las admite.

Grupo	Herramientas	Notas
Listas de tareas	`list_tasklists`, `create_tasklist`, `get_tasklist`, `update_tasklist`, `delete_tasklist`	La eliminación de listas de tareas requiere `confirm: true`; las listas no vacías requieren `force: true`.
Lecturas de tareas	`list_tasks`, `get_task`	Lee desde una lista de tareas. Si se omite `tasklist`, usa `DEFAULT_TASKLIST` o la primera lista de Google.
Resúmenes de tareas	`today`, `overdue`, `upcoming`, `search`, `digest`	Si se omite `tasklist`, lee todas las listas de tareas e incluye contexto de la lista.
Mutaciones de tareas	`clear_completed`, `add`, `complete`, `update`, `uncomplete`, `delete`, `move`	Muta una lista de tareas/tarea a la vez. `clear_completed` requiere `confirm: true`.

Todos los argumentos de tasklist aceptan un ID de lista de tareas o un título exacto. La búsqueda por título de tarea es exacta después de recortar espacios en blanco e ignora mayúsculas y minúsculas.

Para today, overdue, upcoming, search y digest, omitir tasklist lee todas las listas de tareas. Los objetos de tarea devueltos incluyen tasklist_id y tasklist_title; digest etiqueta los elementos con contexto de la lista de tareas.

Para list_tasks, clear_completed, herramientas de tarea única y herramientas de escritura, omitir tasklist usa DEFAULT_TASKLIST, o la primera lista devuelta por Google. Esto evita que escrituras no calificadas toquen todas las listas.

Limitaciones

Estos son límites de la API REST de Google Tasks:

Las fechas de vencimiento son solo de fecha. Google descarta los valores de hora del día en las fechas de vencimiento de tareas.
Las tareas recurrentes no se pueden crear ni leer a través de la API REST de Google Tasks.
clear_completed oculta tareas completadas; no las elimina permanentemente.

Docker Y VPS

Docker:

docker compose up --build

Mantén .env, archivos JSON de OAuth y bases de datos SQLite fuera de imágenes y paquetes públicos.

Las plantillas de VPS/systemd/Caddy están en deploy/:

Reemplaza cada dominio, ruta y usuario de marcador de posición antes de implementar.

Solución De Problemas

Token portador faltante:

HTTP /mcp requiere Authorization: Bearer <token> a menos que el modo de puerta de enlace OAuth esté manejando el cliente.
El modo stdio no usa MCP_BEARER_TOKEN.

La aplicación OAuth de Google está en modo Prueba:

Añade cada usuario de Google inicializado como usuario de prueba.
Los tokens de actualización en modo Prueba pueden expirar después de 7 días.

Discrepancia de URI de devolución de llamada:

GOOGLE_REDIRECT_URI debe coincidir exactamente con una URI de redirección autorizada en Google Cloud.
Para OAuth web local, usa http://127.0.0.1:8787/callback de manera consistente.

Token de actualización de Google caducado o revocado:

Ejecuta google-tasks-mcp-bootstrap nuevamente para la cuenta afectada.
Para modo multi-cuenta, incluye el mismo --account-id que usaste antes.

El cliente MCP OAuth sigue reautorizando:

Asegúrate de que el servidor ejecute una versión con tokens de actualización MCP OAuth persistidos.
Verifica que DB_PATH apunte a almacenamiento persistente y sobreviva a reinicios.
Verifica que MCP_OAUTH_ISSUER sea la URL base HTTPS pública sin barra final.

Más Documentación

MCP_SERVER_GUIDE.md explica modelos de alojamiento, límites de credenciales y opciones de proyecto público vs servicio público.
DISTRIBUTION.md explica la publicación en registros, paquetes y directorios.
.env.example enumera todas las variables de entorno admitidas.
google-tasks-mcp-specifications.md es la fuente de verdad de comportamiento.

Pruebas

pytest