Google Tasks

Acceso completo de lectura y escritura a Google Tasks: crear, actualizar, completar, eliminar, mover y reasignar tareas y listas de tareas, con fechas de vencimiento reales y subtareas, autorizado con tu propio cliente local de OAuth de Google.

GitHub

Documentación

google-tasks-mcp-server

Un servidor MCP para Google Tasks. Proporciona a cualquier cliente MCP (Claude Desktop, Claude Code, Codex, Cursor, etc.) acceso completo de lectura/escritura a tus listas de tareas y tareas: listar, crear, actualizar, completar, eliminar y moverlas, con fechas de vencimiento reales.

No existe un servidor MCP oficial de Google Tasks, así que esto cubre esa necesidad. CRUD completo, flujo de autenticación OAuth para aplicaciones instaladas (tus credenciales nunca salen de tu máquina), TypeScript en todo el proyecto.

Herramientas

Listas de tareas

google_tasks_list_tasklists listar todas las listas de tareas
google_tasks_get_tasklist obtener una lista de tareas
google_tasks_create_tasklist crear una nueva lista de tareas
google_tasks_update_tasklist renombrar una lista de tareas
google_tasks_delete_tasklist eliminar una lista de tareas y todas sus tareas

Tareas

google_tasks_list_tasks listar tareas en una lista, con filtros de fecha de vencimiento/actualización y paginación
google_tasks_get_task obtener una tarea
google_tasks_create_task crear una tarea (opcionalmente como subtarea, opcionalmente posicionada)
google_tasks_update_task actualizar título/notas/fecha de vencimiento/estado
google_tasks_complete_task / google_tasks_reopen_task marcar como completada / no completada
google_tasks_delete_task eliminar una tarea
google_tasks_move_task reordenar, cambiar de padre, o mover una tarea a otra lista
google_tasks_clear_completed_tasks limpiar todas las tareas completadas de una lista

Cada herramienta admite response_format: "markdown" | "json".

Inicio rápido

Desde npm:

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

O no lo instales y deja que tu cliente MCP lo ejecute mediante npx (ver paso 4).

O desde el código fuente:

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

En cualquier caso, sigue la Configuración a continuación para crear tus propias credenciales OAuth de Google y autorizar. No existe una versión compartida o alojada de esto; se comunica directamente con tu propia cuenta de Google.

Configuración

1. Crear un cliente OAuth de Google Cloud

Cada usuario necesita su propio cliente OAuth. No es algo que se pueda compartir, ya que cualquiera que use tu secreto de cliente podría hacerse pasar por tu aplicación (aunque aún necesitaría el consentimiento individual de cada usuario).

Ve a la Consola de Google Cloud, crea (o elige) un proyecto.
APIs y Servicios → Biblioteca → habilita la API de Google Tasks.
APIs y Servicios → Pantalla de consentimiento OAuth (Google ahora lo llama "Plataforma de autenticación de Google"):
- Tipo de usuario: Externo es suficiente para uso personal.
- Completa el nombre de la aplicación y tu correo electrónico para soporte/contacto.
- En Audiencia → Usuarios de prueba, agrega tu propia cuenta de Google. Mientras la aplicación esté en estado "Pruebas", solo los usuarios de prueba listados pueden autorizarla, lo cual es suficiente para ejecutarla tú mismo.
Clientes → Crear Cliente → Tipo de aplicación Aplicación de escritorio. Créalo.
Obtén el ID de cliente y el secreto de cliente, ya sea mediante "Descargar JSON" justo después de la creación o desde la página de detalles del cliente más tarde. La consola de Google no mostrará el texto plano de un secreto nuevamente una vez que navegues fuera, solo podrás descargarlo o regenerarlo, así que si lo pierdes, simplemente agrega un nuevo secreto en lugar de buscar el anterior.
Guarda ese archivo. Por defecto, este servidor lo busca en: ~/.config/google-tasks-mcp-server/client_secret.json (anula la ruta con la variable de entorno GOOGLE_TASKS_CLIENT_SECRET, útil si prefieres mantenerlo dentro del directorio del proyecto, p. ej. ./credentials/client_secret.json. credentials/ ya está en gitignore.)

El archivo debería verse así:

{
  "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. Instalación

Desde npm (nada que compilar):

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

Desde el código fuente:

npm install
npm run build

3. Autorizar (una sola vez)

Si instalaste desde npm:

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

Desde el código fuente:

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

Esto imprime una URL de consentimiento de Google e intenta abrirla en tu navegador predeterminado. Inicia sesión, concede acceso, y redirige de vuelta a un servidor local de corta duración en http://localhost:53682. El token se guarda en caché en ~/.config/google-tasks-mcp-server/token.json (anula con GOOGLE_TASKS_TOKEN_PATH) y se renueva automáticamente a partir de entonces, así que no deberías necesitar ejecutar esto de nuevo a menos que revoques el acceso.

Ejecuta esto en la misma máquina y en la misma terminal regular que usarás a diario. Consulta Solución de problemas a continuación si lo ejecutas desde un contenedor, máquina virtual o shell sandbox donde localhost no se mapea de vuelta a tu navegador.

4. Ejecutarlo

npm start

O conéctalo a un cliente MCP. Para Claude Desktop / Claude Code, agrégalo a tu configuración MCP (generalmente ~/Library/Application Support/Claude/claude_desktop_config.json en macOS).

Usando npm, con tu secreto de cliente en la ruta predeterminada ~/.config/..., esta es la configuración completa:

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

O apuntando a un checkout del código fuente:

{
  "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"
      }
    }
  }
}

Omite el bloque env si guardaste tu secreto de cliente en la ruta predeterminada ~/.config/.... Cierra y vuelve a abrir completamente tu cliente MCP después.

Codex

Codex usa TOML en lugar de JSON. Agrega esto a ~/.codex/config.toml:

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

O deja que la CLI lo escriba por ti:

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

Aumenta startup_timeout_sec si el primer lanzamiento se agota. Un npx en frío descarga el paquete antes de que el servidor pueda responder a initialize, y el margen predeterminado de Codex es lo suficientemente corto como para que esto a veces falle solo en la primera ejecución.

Si tu secreto de cliente no está en la ruta predeterminada, agrega:

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

Verifica que se haya registrado con codex mcp list. La autorización es el mismo paso único de google-tasks-mcp-auth que en cualquier otro lugar: ejecútalo en una terminal normal, no dentro de Codex, ya que necesita abrir un navegador y capturar una redirección de loopback.

Variables de entorno

Variable	Predeterminado	Propósito
`GOOGLE_TASKS_CLIENT_SECRET`	`~/.config/google-tasks-mcp-server/client_secret.json`	Ruta al JSON del cliente OAuth descargado
`GOOGLE_TASKS_TOKEN_PATH`	`~/.config/google-tasks-mcp-server/token.json`	Ruta donde se almacena el token OAuth en caché
`GOOGLE_TASKS_OAUTH_PORT`	`53682`	Puerto de loopback usado solo durante `npm run auth`

Notas de seguridad

El secreto de cliente y el token en caché son archivos planos en disco (modo 0600 para el token). Nunca los confirmes en el repositorio (.gitignore ya excluye client_secret*.json, token.json, credentials/).
El servidor solicita el alcance completo de https://www.googleapis.com/auth/tasks (lectura/escritura). Para acceso de solo lectura, edita TASKS_SCOPE en src/constants.ts a .../auth/tasks.readonly antes de ejecutar npm run auth. Las herramientas de escritura fallarán entonces con un 403 de Google, lo cual es esperado.
Las anotaciones de herramientas marcan las operaciones de eliminación/limpieza como destructiveHint: true para que los clientes MCP puedan advertir o bloquear sobre ellas.
Nada aquí se comunica con ningún servidor excepto las propias APIs de Google y, durante npm run auth, un listener de loopback local. No hay backend de terceros involucrado.

Solución de problemas

npm run auth abre una URL, hago clic en Permitir, y simplemente se queda colgado. El proceso que ejecuta npm run auth no está en la misma máquina/red que el navegador donde haces clic en Permitir. Es común si ejecutas el servidor dentro de un contenedor, entorno de desarrollo remoto o shell sandbox que aísla localhost. Solución: ejecuta npm run auth directamente en una terminal local normal en la máquina cuyo navegador estás usando.

Error [TransformError] ... You installed esbuild for another platform Tu node_modules se instaló en un sistema operativo/arquitectura diferente al que estás ejecutando ahora, p. ej. copiado desde un contenedor Docker o una máquina diferente. Solución: rm -rf node_modules package-lock.json && npm install.

Authorization failed: invalid_client Tu client_secret.json tiene el secreto de cliente incorrecto, generalmente por copiarlo y pegarlo manualmente en lugar de descargarlo directamente. Vuelve a la Consola de Google Cloud, agrega un nuevo secreto de cliente, descárgalo o cópialo directamente, y actualiza tu client_secret.json.

El servidor sale inmediatamente con "No cached Google Tasks token found" Aún no has autorizado, o el flujo no terminó. Ejecuta google-tasks-mcp-auth (instalación npm) o npm run auth (checkout del código fuente) antes de iniciar el servidor.

Desarrollo

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

Prueba con el MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Contribuciones

Se aceptan issues y PRs. Esto cubre toda la superficie de la API de Tasks pero no se ha probado en todos los casos límite, así que si encuentras un error o quieres una funcionalidad, abre un issue.

Licencia

MIT, ver LICENSE.