mariana-google-mcp

Пользовательский сервер MCP (Model Context Protocol), который предоставляет Claude Code доступ к Gmail, Google Календарю и Google Контактам — с настройками безопасности по умолчанию.

Философия дизайна

Этот сервер создан для пользователя, который хочет, чтобы ИИ помогал управлять рабочим пространством Google без риска случайного повреждения данных:

Никакой отправки писем. Вы можете создавать черновики, но для отправки требуется ручное действие в Gmail.
Никакого удаления. В Gmail используется метка "To Be Deleted" (мягкое удаление). В Календаре к заголовкам событий добавляется префикс "DELETE - ". Вы проверяете и подтверждаете действия в интерфейсе Google.
Каждое изменение логируется. Журнал действий в формате JSONL (только для добавления) записывает каждую операцию записи с отметками времени, названием инструмента, аккаунтом и кратким описанием.
Поддержка нескольких аккаунтов. Управляйте личными и рабочими аккаунтами с помощью именованных псевдонимов.

Настройка

1. Проект Google Cloud

Перейдите в Google Cloud Console
Создайте новый проект (или используйте существующий)
Включите следующие API:
- Gmail API
- Google Calendar API
- People API (для контактов)
Создайте учетные данные OAuth 2.0:
- Тип приложения: Desktop app
- Скачайте идентификатор клиента (client ID) и секрет клиента (client secret)

2. Установка и сборка

git clone https://github.com/marianasmall/mariana-google-mcp.git
cd mariana-google-mcp
npm install
npm run build

3. Добавление в Claude Code

Добавьте это в ваш ~/.claude.json в раздел mcpServers:

{
  "mcpServers": {
    "mariana-google-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mariana-google-mcp/dist/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Замените /path/to/ на фактический путь к вашему клону и введите свои учетные данные OAuth.

4. Аутентификация

После перезапуска Claude Code запустите инструмент google_auth. Он откроет окно браузера для согласия OAuth. После авторизации ваш токен будет сохранен локально и будет обновляться автоматически.

Доступные инструменты (19)

Аутентификация и статус

Инструмент	Описание
`google_auth`	Аутентификация аккаунта Google через OAuth в браузере
`google_status`	Проверка состояния подключения для всех настроенных аккаунтов

Gmail (9 инструментов)

Инструмент	Описание
`gmail_search`	Поиск сообщений с использованием синтаксиса запросов Gmail
`gmail_read`	Чтение конкретного сообщения по ID (полное содержимое)
`gmail_list_labels`	Список всех меток/папок Gmail
`gmail_draft`	Создание черновика письма (НЕ отправляет)
`gmail_create_label`	Создание новой метки (поддерживает вложенность через `/`)
`gmail_apply_label`	Применение метки к одному или нескольким сообщениям
`gmail_remove_label`	Удаление метки с одного или нескольких сообщений
`gmail_create_filter`	Создание правила фильтрации (критерии соответствия → действия)
`gmail_move_to_delete`	Мягкое удаление: перемещение сообщений в метку "To Be Deleted"

Календарь (6 инструментов)

Инструмент	Описание
`calendar_list`	Список предстоящих событий календаря
`calendar_search`	Поиск событий по ключевому слову
`calendar_get`	Получение полной информации о конкретном событии
`calendar_create`	Создание события (по умолчанию НЕ отправляет приглашения)
`calendar_update`	Изменение существующего события (по умолчанию НЕ уведомляет участников)
`calendar_flag_delete`	Мягкое удаление: добавление префикса "DELETE - " к заголовку события
`calendar_availability`	Проверка статуса "свободен/занят" для диапазона дат

Контакты (2 инструмента)

Инструмент	Описание
`contacts_search`	Поиск контактов по имени, email или телефону
`contacts_list`	Список контактов, опционально отфильтрованный по группе

Поддержка нескольких аккаунтов

Вы можете аутентифицировать несколько аккаунтов Google с понятными именами:

google_auth account_name: "primary"
google_auth account_name: "newsletters"
google_auth account_name: "work"

Большинство инструментов принимают необязательный параметр account. Если он опущен, используется аккаунт по умолчанию. Используйте google_status, чтобы увидеть все настроенные аккаунты и их состояние.

Файлы конфигурации

Вся конфигурация хранится в ~/.config/mariana-google-mcp/:

Файл	Назначение
`config.json`	Реестр аккаунтов (имена, хеши email, настройки по умолчанию)
`tokens/<hash>.json`	Токены OAuth для каждого аккаунта (автоматически обновляются)
`actions.jsonl`	Журнал всех изменений (только для добавления)

Токены хранятся по хешу email, а не в открытом виде, для дополнительного уровня безопасности.

Журнал действий

Каждая операция записи (черновики, создание/обновление календаря, мягкое удаление) записывается в ~/.config/mariana-google-mcp/actions.jsonl в следующем формате:

{"timestamp":"2026-04-03T10:30:00.000Z","tool":"gmail_draft","account":"primary","summary":"Draft created: subject='Meeting follow-up'"}

Журнал доступен только для добавления и никогда не изменяется сервером. Проверяйте его в любое время, чтобы провести аудит действий Claude.

Форк и использование

Чтобы использовать это со своим аккаунтом Google:

Сделайте форк этого репозитория
Создайте свой проект Google Cloud и учетные данные OAuth (см. "Настройка" выше)
Соберите проект и укажите в конфигурации Claude Code путь к dist/index.js вашего форка
Запустите google_auth для аутентификации

Изменения в коде не требуются — все данные, специфичные для аккаунта, хранятся в файлах конфигурации и переменных окружения.

Технологический стек

TypeScript
@modelcontextprotocol/sdk — реализация протокола MCP
googleapis — клиент Google API
google-auth-library — управление токенами OAuth2
zod — валидация входных данных

Лицензия

MIT

Mariana Google MCP