google-tasks-mcp-server

MCP-сервер (stdio) для работы с Google Tasks. Предоставляет CRUD для списков задач и задач, переключение выполнения, сортировку и перемещение, а также массовое скрытие выполненных задач.

Официальный набор Workspace MCP-серверов от Google (Gmail / Calendar / Drive и т. д.) не включает Tasks, поэтому этот сервер создан, чтобы закрыть этот пробел.

Принципы проектирования

• Учётные данные передаются через файл. Путь к загруженному из GCP client_secret_*.json задаётся переменной окружения. Это позволяет не указывать Client Secret открытым текстом в конфигурации MCP.

• Первичная аутентификация выполняется в отдельном CLI. Так как MCP-сервер занимает stdout для JSON-RPC, вывод запуска браузера или логов в этот поток нарушит протокол. Вынеся аутентификацию в npm run auth, можно избежать конфликтов и упростить диагностику при сбоях.

• Область доступа — только tasks. Запрашивается исключительно https://www.googleapis.com/auth/tasks.

• Для обновлений используется patch. update стирает неуказанные поля, поэтому для частичного обновления всегда применяется patch.

Related MCP server: Mini Task MCP Server

Установка

1. Подготовка GCP

1. Включите Google Tasks API на странице APIs & Services → Library.

2. В разделе Credentials создайте OAuth 2.0 Client ID. Тип приложения — Desktop app.

   • Тип Desktop app позволяет использовать любой loopback-порт как redirect URI, поэтому регистрировать redirect URI не нужно.

3. Скачайте JSON-файл (client_secret_xxx.json).

4. Если экран согласия OAuth имеет статус «Тестирование», добавьте свой аккаунт Google в тестовые пользователи.

2. Сборка

npm install
npm run build

3. Первичная аутентификация

Укажите путь к client_secret_*.json и выполните аутентификацию. Откроется браузер — нужно будет дать согласие.

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

Токен сохраняется в ~/.config/google-tasks-mcp-server/token.json с правами 0600. В дальнейшем он автоматически обновляется через refresh-токен, поэтому эта операция нужна только один раз.

4. Регистрация в MCP-клиенте

Для 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

Если запись делается напрямую в .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"
      }
    }
  }
}

Переменные окружения

Инструменты

Если tasklist не указан, используется @default (список задач по умолчанию).

Списки задач

Задачи

Примечания по спецификации

• В срок не сохраняется время. Хотя due передаётся в формате RFC 3339, Google Tasks хранит только дату.

• Для получения выполненных задач необходим параметр showHidden. Одного showCompleted: true недостаточно, чтобы вернуть задачи, завершённые в других клиентах, поэтому при showCompleted: true сервер автоматически добавляет showHidden.

• clear-completed-tasks — это не удаление. Задачи просто скрываются, и их можно получить через showHidden: true.

• Фильтр по срок скорректирован на «включая указанную дату». В Google Tasks API параметр dueMax на уровне дней является исключающим: даже при передаче 23:59:59 текущего дня не возвращается ни одной задачи со сроком в этот день (нужно передавать 00:00 следующего дня). Так как это противоречит интуиции, сервер нормализует dueMin / dueMax по границам дат и приводит оба параметры к поведению, включающему указанную дату.

Разработка

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

Лицензия

MIT

Скрипт настройки

Кратко опишите, что после шагов в консоли GCP (включение Tasks API, создание OAuth-клиента типа Desktop, скачивание JSON) остальное можно выполнить одной командой.

./scripts/setup.sh

Скрипт автоматически ищет client_secret*.json в ~/Downloads, проверяет его тип, помещает в ~/.config/google-tasks-mcp-server/ с правами 600 и затем выполняет сборку, первичную аутентификацию и регистрацию MCP-сервера. Если файл находится в другом месте, передайте путь.

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