mcp-google-contacts

v1.0.0

Published

5 days ago

MCP server for Google Contacts (People API) — search, read, create, update and delete contacts, manage contact groups and run batch operations. For Claude, Cursor, Codex and other AI clients.

Downloads

740

0High
0Medium
0Low

gistrec

mcp model-context-protocol google google-contacts people-api contacts contact-groups claude cursor codex

Google Contacts MCP

English | Русский

A1 Google Contacts MCP позволяет AI-приложению управлять вашей адресной книгой Google на естественном языке. Можно найти контакт, создать или обновить его, разложить контакты по ярлыкам, выполнить пакетный импорт и чистку и превратить автосохранённые «Другие контакты» в настоящие.

Сервер работает с Google People API — API, на котором построены Google Контакты, — через ваш Google-аккаунт. Он защищает каждое обновление от параллельных правок, делает чтение компактным за счёт явных масок полей и явно показывает ограничения People API, а не создаёт впечатление, что с контактами можно сделать всё.

25 инструментов. Список, поиск и чтение контактов, создание, обновление и удаление по одному или пакетами, управление группами контактов и их составом, доступ к «Другим контактам».
Подключение из диалога. Скажите «подключи Google Контакты»: сервер проведёт через создание OAuth-клиента, поймает редирект Google на 127.0.0.1 с PKCE и сам сохранит токены — без конфигов и перезапуска.
Обновления не затирают чужие правки. Каждое обновление защищено etag: если контакт изменился где-то ещё после чтения, запись завершится ошибкой, а не молча перезапишет параллельную правку.
Удаление — настоящее. В People API нет корзины; удаление контакта или группы необратимо, и сервер помечает эти инструменты как разрушительные, чтобы AI-приложение спросило заранее.
Минимальные scope Google. Используется contacts для чтения и записи — для read-only-установки достаточно contacts.readonly — плюс contacts.other.readonly только для «Других контактов», без широкого доступа к аккаунту.

Начните с запроса, который только читает данные:

Найди в моих контактах всех из Acme и покажи их email и телефоны.

Подключить сервер · Посмотреть сценарии · Открыть техническую документацию

Увидеть работу за минуту

Вы: Покажи карточку контакта Jane Doe — email, телефон и компанию.
Ассистент: Находит контакт и показывает запрошенные поля. Ничего не меняется.
Вы: Поменяй её телефон на +1 415 555 0100 и добавь её в ярлык «Клиенты».
Ассистент: Показывает контакт и предлагаемое изменение, затем запрашивает подтверждение перед записью.
Вы: Подтверждаю.
Ассистент: Применяет обновление под защитой etag и добавляет ярлык. Если контакт за это время изменился где-то ещё, запись завершится ошибкой, а не перезапишет правку.

Содержание

Быстрый старт

Нужны Node.js 20+ и Google-аккаунт. Учётные данные при установке не нужны: сервер подключается прямо в диалоге.

Добавьте сервер в AI-приложение.
Скажите «подключи Google Контакты» — ассистент проведёт создание OAuth-клиента и выдачу доступа, не трогая конфиги.
Отправьте запрос, который только читает данные.

В приложении: откройте Settings → MCP servers, нажмите Add server, выберите STDIO, укажите команду npx -y mcp-google-contacts@latest и переменные окружения GOOGLE_CONTACTS_CLIENT_ID, GOOGLE_CONTACTS_CLIENT_SECRET, GOOGLE_CONTACTS_REFRESH_TOKEN, затем нажмите Save, потом Restart.

В командной строке:

codex mcp add google-contacts \
  -- npx -y mcp-google-contacts@latest

codex mcp list

Документация Codex MCP

claude mcp add \
  --transport stdio --scope user google-contacts \
  -- npx -y mcp-google-contacts@latest

claude mcp list

Документация Claude Code MCP

Актуальный официальный путь — Settings → Extensions. Для пользовательского desktop extension откройте Advanced settings → Extension Developer → Install Extension…, выберите файл .mcpb и следуйте подсказкам.

Этот репозиторий сейчас публикует npm-пакет со stdio и пока не содержит .mcpb. Поэтому используйте приведённый ниже JSON stdio-конфиг как fallback только в сборках Claude Desktop, где ещё поддерживается локальная конфигурация:

{
  "mcpServers": {
    "google-contacts": {
      "command": "npx",
      "args": ["-y", "mcp-google-contacts@latest"]
    }
  }
}

В таких сборках сохраните его в ~/Library/Application Support/Claude/claude_desktop_config.json на macOS или %APPDATA%\Claude\claude_desktop_config.json на Windows.

Документация Claude Desktop MCP

Добавьте в ~/.cursor/mcp.json на macOS/Linux или %USERPROFILE%\.cursor\mcp.json на Windows:

{
  "mcpServers": {
    "google-contacts": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-contacts@latest"]
    }
  }
}

Документация Cursor MCP

Запустите MCP: Open User Configuration и добавьте:

{
  "servers": {
    "google-contacts": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-contacts@latest"]
    }
  }
}

Проверьте сервер командой MCP: List Servers.

Документация VS Code MCP

Что можно поручить

Найти и посмотреть контакты

Найди всех из Acme и покажи их email и телефоны.
Покажи, кто входит в ярлык «Клиенты».
Выведи контакты, изменившиеся с прошлой синхронизации.

Поддерживать адресную книгу в порядке

Создай контакт Jane Doe с email, телефоном и компанией.
Обнови телефон или должность контакта.
Импортируй пятьдесят человек одним пакетом или удали устаревшие контакты одним вызовом.

Наводить порядок с ярлыками

Создай ярлык «Клиенты» и добавь в него эти контакты.
Переименуй ярлык или перенеси контакт из одного ярлыка в другой.
Удали ярлык, не удаляя его контакты, — или вместе с ними, но только по явной просьбе.

Работать с «Другими контактами»

Покажи адреса, которые Google сохранил автоматически, но которых нет в моих контактах.
Скопируй один из них в «Мои контакты» как настоящий контакт.

Как меняется контакт

У каждого контакта, группы и «другого контакта» есть полное имя ресурса (people/c..., contactGroups/..., otherContacts/...); инструменты адресуют записи по нему, ровно в том виде, в каком его возвращает API.
Чтение возвращает только поля из маски полей (по умолчанию: имена, email, телефоны, организации, членство в группах). Отсутствующее поле может быть просто вне маски, а не пустым.
Обновление заменяет каждую переданную группу полей целиком и защищено etag: если контакт изменился где-то ещё после чтения, запись завершится ошибкой, а не перезапишет параллельную правку.
Удаление необратимо. В People API нет корзины и отмены.

Поиск работает по кэшу, который может отставать от свежих записей на несколько секунд, и возвращает не более 30 результатов. «Другие контакты» — адреса, которые Google сохраняет автоматически, — можно только читать или копировать в «Мои контакты», но не редактировать на месте. Для фотографий контактов отдельного инструмента нет; до этих эндпоинтов достаёт raw_request.

Что может измениться

| Операция | Что происходит | Граница подтверждения | |---|---|---| | Чтение, поиск или пакетное чтение контактов и групп | Читает данные контактов | Ничего не меняет | | Создание контакта, группы или пакета контактов | Добавляет записи | Меняет Google Контакты | | Обновление контакта или переименование группы | Заменяет переданные группы полей, под защитой etag | Меняет контакт | | Изменение состава ярлыка | Добавляет или снимает ярлык у выбранных контактов | Меняет контакты | | Копирование «другого контакта» | Добавляет настоящий контакт в «Мои контакты» | Меняет Google Контакты | | Удаление контакта, группы или пакета | Удаляет записи безвозвратно; удаление группы удаляет её контакты только по явному запросу | Разрушительно | | Технический запрос API | Может вызвать метод API без отдельного инструмента | Потенциально разрушительно |

Как AI-приложение просит подтверждение, определяет само приложение. Сервер помечает операции чтения, записи и удаления, чтобы оно отличило проверку от рабочего изменения.

Как получить доступ

Google Contacts требует OAuth 2.0: одного API-ключа недостаточно. Путей два, и первый не требует править конфигурационные файлы.

Подключение из диалога (рекомендуемый путь)

Скажите «подключи Google Контакты», и ассистент пройдёт флоу вместе с вами:

setup_instructions выдаёт чек-лист: создать или выбрать проект Google Cloud, включить Google People API, настроить consent screen и создать OAuth-клиент типа Desktop app.
Скачайте JSON этого клиента («Download JSON») и передайте ассистенту путь к файлу — set_client сохранит его с правами только для владельца. Секрет через переписку не проходит.
start_login возвращает ссылку на согласие Google. Откройте её на этой же машине и подтвердите доступ: код возвращается на одноразовый слушатель 127.0.0.1 (PKCE), а не в чат.
finish_login меняет код на токены и кладёт их в ~/.config/mcp-google-contacts/credentials.json (права 0600) и проверяет их реальным вызовом Google People API — так невключённый API ловится сразу.

Токены перечитываются на каждый вызов, поэтому подключение действует немедленно — перезапускать AI-приложение не нужно. auth_status показывает состояние, logout отзывает токен и удаляет его.

Переменные окружения (CI и автоматические установки)

Создайте или выберите проект Google Cloud и включите People API.
Настройте OAuth consent screen и создайте OAuth-клиент типа Desktop app.
Авторизуйте Google-аккаунт, контактами которого хотите управлять. OAuth 2.0 Playground поможет получить refresh token, если включить Use your own OAuth credentials.

Запросите минимальные scope под свои задачи:

https://www.googleapis.com/auth/contacts
https://www.googleapis.com/auth/contacts.other.readonly

contacts покрывает чтение и запись контактов и групп; для read-only-установки достаточно одного contacts.readonly. contacts.other.readonly нужен только инструментам «Других контактов». Ошибка 403 на одном инструменте обычно означает, что refresh token выпущен без нужного этому инструменту scope, — пройдите авторизацию заново, добавив недостающий scope.

Refresh token OAuth-приложения в режиме Testing может истечь через семь дней. Для долгого доступа опубликуйте OAuth-приложение или используйте Internal-приложение в домене Workspace. Храните client secret и refresh token как пароли.

Конфигурация

Все переменные необязательные — без единой из них сервер подключается из диалога.

| Переменная | Обязательна | Описание | |---|---|---| | GOOGLE_CONTACTS_CLIENT_ID | Нет* | OAuth client ID. | | GOOGLE_CONTACTS_CLIENT_SECRET | Нет* | OAuth client secret. | | GOOGLE_CONTACTS_REFRESH_TOKEN | Нет* | OAuth refresh token. | | GOOGLE_CONTACTS_ACCESS_TOKEN | Нет* | Короткоживущая альтернатива OAuth-тройке (~1 ч). | | GOOGLE_CONTACTS_OAUTH_PORT | Нет | Фиксированный порт loopback-слушателя для входа из диалога; нужен при пробросе портов по SSH. | | GOOGLE_CONTACTS_API_BASE | Нет | Переопределяет базовый URL Google People API. | | GOOGLE_CONTACTS_TIMEOUT_MS | Нет | Тайм-аут одного запроса; по умолчанию 60000 мс. | | GOOGLE_CONTACTS_MAX_RETRIES | Нет | Повторы временных ошибок; по умолчанию 3. |

* Передайте OAuth-тройку или access token. Совсем без учётных данных сервер всё равно стартует и завершает MCP-handshake; первый же вызов инструмента назовёт, какие именно переменные задать.

Данные, лимиты и работа в фоне

Запросы идут в Google. Локальный сервер обновляет OAuth-токены Google и вызывает People API на people.googleapis.com. Анонимная телеметрия содержит ID установки, версию пакета, версии AI-клиента и платформы и имена инструментов — но не OAuth-токены, данные контактов, аргументы или промпты. Чтобы отключить её, задайте ASKADS_TELEMETRY=0.
Квоты Google — на пользователя и небольшие. Квота People API по умолчанию даёт примерно 90 чтений и 90 записей на пользователя в минуту, поэтому пакетные инструменты выгоднее циклов одиночных вызовов; изменяющие пакеты нужно выполнять по одному. При 429 сервер делает паузу и повторяет; чтение также повторяется после сетевых и 5xx ошибок, а запись после неопределённой ошибки не повторяется.
Постоянного опроса нет. Сервер работает только при вызове. list_contacts поддерживает sync-токены, поэтому AI-приложение с заданиями по расписанию может периодически забирать только изменения; sync-токен истекает примерно через семь дней, после чего нужно заново получить полный список.

Техническая документация

Каталог MCP-возможностей — страницы по пользовательским задачам для каждого инструмента.
Все инструменты и параметры
Документация по разработке
Документация по публикации
Справочник Google People API

Поддержка

Нашли ошибку или не хватает сценария? Создайте issue или напишите в Telegram.