gsheets-mcp

Локальный MCP-сервер (Model Context Protocol), который позволяет Claude читать и записывать ваши Google-таблицы через Google Sheets API v4.

Он полностью работает на вашей собственной машине. Вы проходите аутентификацию со своим аккаунтом Google через OAuth2 (поток «installed app» / Desktop), и ваши данные никогда не проходят через сторонние серверы.

Бесплатно и с открытым исходным кодом под лицензией MIT. Никакой телеметрии, никаких сторонних серверов.

🌐 Сайт: https://gsheets-mcp.trombella.org/

Что вы получаете

Большинство инструментов принимают ID таблицы — длинную строку из URL таблицы: https://docs.google.com/spreadsheets/d/<THIS_IS_THE_ID>/edit. Вы также можете узнать ID с помощью list_spreadsheets, а не копировать их вручную.

Related MCP server: sheetsdb-mcp-server

Предварительные требования

• Node.js 18+ (node --version).

• Аккаунт Google.

Часть 1 — Настройка Google Cloud (один раз)

Вам нужен OAuth-клиент «Desktop app», чтобы сервер мог запросить у вас разрешение на доступ к вашим таблицам.

1. Создайте проект в Google Cloud

1. Перейдите на https://console.cloud.google.com/.

2. Верхняя панель → раскрывающийся список проектов → New Project. Дайте ему имя (например, gsheets-mcp) и создайте его. Убедитесь, что он выбран.

2. Включите API

1. Перейдите в APIs & Services → Library (https://console.cloud.google.com/apis/library).

2. Найдите Google Sheets API, откройте его и нажмите Enable.

3. Найдите Google Drive API, откройте его и нажмите Enable.

Drive API используется только инструментом list_spreadsheets для перечисления ваших таблиц через scope drive.readonly (только чтение). Он не используется для изменения, перемещения или удаления файлов.

3. Настройте экран согласия OAuth

1. Перейдите в APIs & Services → OAuth consent screen.

2. User type: External → Create. (Тип Internal доступен только в организациях Google Workspace.)

3. Заполните обязательные поля: название приложения (например, gsheets-mcp), вашу электронную почту в полях User support email и Developer contact. Остальные поля можно оставить пустыми. Save and continue.

4. Scopes: добавление областей доступа здесь можно пропустить (приложение запрашивает их при входе). Save and continue.

5. Test users: нажмите Add users и добавьте свой собственный адрес Google. Это обязательно — в режиме «Testing» авторизовать приложение могут только перечисленные тестовые пользователи. Save and continue.

6. Оставьте приложение в режиме Testing. Это нормально для личного использования и никогда не истекает для вашего собственного тестового аккаунта. (Публикация в «Production» запустит проверку приложения Google, которая вам здесь не нужна.)

4. Создайте учётные данные OAuth-клиента

1. Перейдите в APIs & Services → Credentials.

2. Нажмите Create Credentials → OAuth client ID.

3. Application type: Desktop app. Дайте ему имя (например, gsheets-mcp desktop). Нажмите Create.

4. В диалоге подтверждения нажмите Download JSON. Этот файл содержит ваши client_id и client_secret.

5. Разместите файл учётных данных

Сохраните загруженный файл как credentials.json в каталоге конфигурации:

mkdir -p ~/.config/gsheets-mcp
mv ~/Downloads/client_secret_*.json ~/.config/gsheets-mcp/credentials.json

Держите этот файл в тайне — он игнорируется git. Вы можете переопределить его расположение с помощью переменной окружения GSHEETS_MCP_CREDENTIALS (см. .env.example).

Часть 2 — Установка и сборка

Из папки проекта:

npm install
npm run build

Часть 3 — Вход в систему (один раз)

Запустите интерактивный вход. В браузере откроется экран согласия Google; подтвердите доступ, и токен будет сохранён в ~/.config/gsheets-mcp/token.json (в дальнейшем он будет обновляться автоматически).

npm run login
# equivalently: node dist/index.js login

Поскольку приложение находится в режиме Testing, Google показывает предупреждение «Google hasn't verified this app». Это ожидаемо для вашего собственного приложения — нажмите Advanced → Go to gsheets-mcp (unsafe) и продолжайте. Затем предоставьте два запрошенных разрешения (см. ниже).

Когда увидите ✅ Authorization complete в терминале, всё готово.

Запрашиваемые области доступа:

• https://www.googleapis.com/auth/spreadsheets — чтение и запись ваших таблиц.

• https://www.googleapis.com/auth/drive.readonly — только чтение, используется только инструментом list_spreadsheets для перечисления ваших таблиц. Он не может изменять или удалять файлы.

Чтобы отозвать доступ в любое время, посетите https://myaccount.google.com/permissions.

Примечание: если вы обновите сервер и запрашиваемые области доступа изменятся, нужно снова запустить npm run login — ранее предоставленное согласие не покрывает новые области. Это также касается каждой машины (каждый компьютер хранит свой собственный токен).

Часть 4 — Добавление сервера в Claude Desktop

Откройте файл конфигурации Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Добавьте запись gsheets в раздел mcpServers, указав скомпилированную точку входа. Используйте абсолютный путь к dist/index.js в этом проекте:

{
  "mcpServers": {
    "gsheets": {
      "command": "node",
      "args": ["/absolute/path/to/google-sheets-mcp/dist/index.js"]
    }
  }
}

Сохраните файл и полностью закройте и снова откройте Claude Desktop. Теперь вы должны увидеть доступные инструменты gsheets. Попробуйте попросить Claude, например:

«Список моих Google-таблиц, затем прочитай A1:C5 из таблицы с именем 'Budget'.»

Использование с Claude Code

claude mcp add gsheets -- node /absolute/path/to/google-sheets-mcp/dist/index.js

Примеры использования (что спросить у Claude)

• Список: «Список моих Google-таблиц» / «Найди мои таблицы, в названии которых есть 'budget'.»

• Информация: «Какие вкладки есть в таблице <ID>?» (возвращает точные названия вкладок для использования).

• Чтение: «Прочитай диапазон Foglio1!A1:D10 из таблицы <ID>.»

• Обновление: «Запиши значения [[\"Name\",\"Score\"],[\"Ada\",42]] начиная с Foglio1!A1 в таблице <ID>.»

• Добавление: «Добавь строку [\"Grace\", 99] в Foglio1 в таблице <ID>.»

⚠️ Примечание: названия вкладок локализованы

Диапазоны используют название вкладки (листа), например Sheet1!A1:D10. Но название вкладки по умолчанию зависит от языка вашего аккаунта Google: на английском это Sheet1, на итальянском — Foglio1, на испанском — Hoja1, на французском — Feuille1 и так далее. Использование неправильного названия приводит к Unable to parse range: ….

Если вы не уверены в настоящем названии вкладки, откройте таблицу и посмотрите ярлычок вкладки внизу, либо просто попросите Claude прочитать всю таблицу, передав только название вкладки в качестве диапазона (например, Foglio1). Отдельный инструмент get_sheet_info, который выводит точные названия вкладок, запланирован в дорожной карте.

Справочник по конфигурации

Всё опционально; значения по умолчанию работают из коробки. См. .env.example.

Для headless / HTTP режима (см. ниже) вы можете вместо этого указать учётные данные через переменные окружения:

Удалённое / мобильное использование (продвинутый уровень)

Транспорт по умолчанию — stdio (локальный). Сервер также может работать как удалённый MCP-коннектор по HTTP, чтобы вы могли подключаться к нему с клиентов, которые не могут запускать локальный процесс, — например, из мобильного приложения Claude:

MCP_AUTH_TOKEN=$(openssl rand -hex 32) npm run serve:http   # listens on :8000/mcp

Каждый запрос должен отправлять Authorization: Bearer <MCP_AUTH_TOKEN>. Поскольку эта конечная точка может записывать в ваши таблицы, всегда помещайте её за сетевым шлюзом (Cloudflare Access, VPN) в дополнение к bearer-токену — никогда не открывайте её напрямую в интернет.

Готовый аддон Home Assistant OS для личной постоянно включённой настройки (за Cloudflare Tunnel) находится в ha-addon/gsheets-mcp/ — полная пошаговая инструкция в его DOCS.md.

Устранение неполадок

• «Not authenticated. Run the one-time login first» — вы ещё не вошли в систему или файл токена отсутствует. Запустите npm run login.

• «OAuth client credentials not found» — credentials.json находится не там, где его ожидает сервер. Проверьте Часть 1, шаг 5.

• 403 access_denied в браузере — ваш аккаунт Google не добавлен в тестовые пользователи. Добавьте его в разделе OAuth consent screen → Test users (Часть 1, шаг 3.5).

• «Request had insufficient authentication scopes» — ваш сохранённый токен был создан до изменения областей доступа (например, list_spreadsheets требует drive.readonly). Запустите npm run login снова, чтобы повторно дать согласие.

• Unable to parse range: … — неправильное название вкладки. Названия вкладок локализованы (Foglio1 на итальянском, Sheet1 на английском). Используйте get_sheet_info, чтобы увидеть точные названия.

• Предупреждение об отсутствии refresh_token — отзовите доступ приложения на https://myaccount.google.com/permissions и запустите npm run login снова.

• Инструменты не появляются в Claude Desktop — убедитесь, что путь в claude_desktop_config.json абсолютный и указывает на dist/index.js, что вы запускали npm run build и полностью перезапустили Claude Desktop.

Разработка

npm run build       # compile to dist/
npm run watch       # recompile on change
npm run typecheck   # type-check without emitting

Структура исходников: src/index.ts (точка входа), src/auth.ts (OAuth), src/sheetsClient.ts и src/driveClient.ts (обёртки API), src/tools/* (по одному файлу на каждый MCP-инструмент).

Лицензия

Выпущено под лицензией MIT. Вы можете свободно использовать, изменять и распространять его. Если он сэкономил вам время, вы можете поддержать разработку чашкой кофе — ссылка на сайте. ☕

Не аффилировано с Google и не одобрено Google. «Google Sheets» — товарный знак Google LLC.