google-tasks-mcp-server

Servidor MCP (stdio) para gestionar Google Tasks. Ofrece CRUD de listas de tareas y de tareas, alternar entre completada y no completada, reordenar y mover, y ocultar en bloque las tareas completadas.

Como los servidores MCP oficiales de Workspace de Google (Gmail / Calendar / Drive, etc.) no incluyen Tasks, este servidor se creó para cubrir ese vacío.

Principios de diseño

• Las credenciales se pasan mediante un archivo. La ruta del client_secret_*.json descargado de GCP se indica con una variable de entorno. Así no hace falta escribir el Client Secret en texto plano en el archivo de configuración de MCP.

• La autenticación inicial se realiza en una CLI independiente. Como el servidor MCP ocupa stdout con el protocolo JSON-RPC, si se mezclan el lanzamiento del navegador o los registros de log, el protocolo se rompe. Al separar la autenticación en npm run auth, se evita ese conflicto y también es más fácil aislar los fallos.

• El ámbito (scope) es solo Tasks. Solo se solicita https://www.googleapis.com/auth/tasks.

• La actualización se hace con patch. Como update elimina los campos no especificados, para las actualizaciones parciales se usa siempre patch.

Related MCP server: Mini Task MCP Server

Configuración

1. Preparación en GCP

1. Habilita la Google Tasks API en APIs y servicios → Biblioteca.

2. Crea un ID de cliente de OAuth 2.0 en Credenciales. El tipo de aplicación es Aplicación de escritorio.

   • Como el tipo de aplicación de escritorio permite usar cualquier puerto loopback como redirección, no es necesario registrar una URI de redireccionamiento.

3. Descarga el JSON (client_secret_xxx.json).

4. Si la pantalla de consentimiento de OAuth está en estado «Prueba», añade tu propia cuenta de Google como usuario de prueba.

2. Compilar

npm install
npm run build

3. Autenticación inicial

Indica la ruta de client_secret_*.json y autentícate. Se abrirá el navegador, así que da tu consentimiento.

GOOGLE_TASKS_CLIENT_SECRET_PATH=~/path/to/client_secret_xxx.json npm run auth

El token se guarda en ~/.config/google-tasks-mcp-server/token.json con permisos 0600. A partir de entonces se renueva automáticamente con el token de actualización, por lo que este paso solo es necesario la primera vez.

4. Registrar en el cliente MCP

En el caso de Claude Code:

claude mcp add google-tasks \
  -e GOOGLE_TASKS_CLIENT_SECRET_PATH=$HOME/path/to/client_secret_xxx.json \
  -- node /absolute/path/to/google-tasks-mcp-server/dist/index.js

Si se escribe directamente en .mcp.json:

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

Variables de entorno

Herramientas

Cuando se omite, tasklist usa @default (la lista de tareas predeterminada).

Listas de tareas

Tareas

Notas sobre la especificación

• En la fecha límite no se guarda la hora. due se pasa en RFC 3339, pero Google Tasks conserva solo la parte de la fecha.

• Para obtener las tareas completadas se necesita showHidden. Con solo showCompleted: true no se devuelven las tareas completadas en otros clientes, así que este servidor añade showHidden automáticamente cuando showCompleted: true.

• clear-completed-tasks no es un borrado. Solo las oculta, de modo que se pueden recuperar con showHidden: true.

• El filtro de fecha límite se corrige para que «incluya el día especificado». El dueMax de la Google Tasks API es exclusivo a nivel de día: aunque se pasen las 23:59:59 del día actual, no se devuelve ninguna tarea con vencimiento ese día (hay que pasar las 00:00 del día siguiente). Como resulta contraintuitivo, este servidor normaliza dueMin / dueMax a los límites del día para que ambos incluyan el día especificado.

Desarrollo

npm run typecheck   # 型チェックのみ
npm run build       # dist/ に出力
npm run auth        # 初回認証

Licencia

MIT

Script de instalación

Después de completar los pasos en la consola de GCP (habilitar la Tasks API, crear el cliente OAuth de tipo aplicación de escritorio y descargar el JSON), se puede ejecutar el resto de una sola vez.

./scripts/setup.sh

Busca automáticamente client_secret*.json en ~/Downloads, verifica su tipo y lo coloca en ~/.config/google-tasks-mcp-server/ con permisos 600, y después realiza la compilación, la autenticación inicial y el registro del servidor MCP. Si el archivo está en otro lugar, se indica la ruta.

./scripts/setup.sh /path/to/client_secret.json