MCP Google Sheets Server

Читайте, записывайте и управляйте Google Sheets из Claude Desktop, Claude Code и любого AI-клиента, совместимого с Model Context Protocol (MCP).

Легкий, готовый к производству сервер Model Context Protocol (MCP), который предоставляет API Google Sheets для Claude и других LLM-агентов. Автоматизируйте работу с таблицами, создавайте инструменты AI-агентов для логирования в таблицы, синхронизируйте конвейеры данных с таблицами вашей команды или позвольте Claude редактировать документ за вас — всё с помощью одного MCP-сервера.

Содержание

• Зачем

• Возможности

• Быстрый запуск

• Настройка

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

  • 2. Включите Sheets API

  • 3. Создайте учетные данные OAuth 2.0

  • 4. Установите сервер

  • 5. Авторизуйте

• Регистрация в вашем MCP-клиенте

  • Claude Desktop

  • Claude Code

• Доступные инструменты

• Примеры использования

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

• Безопасность

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

• Разработка

• Лицензия

Зачем

Если вы хотели, чтобы Claude обновлял Google Sheet — трекер вакансий, журнал привычек, панель проекта — без переключения окон, этот сервер предоставляет недостающий инструмент. Это естественный аналог официального MCP-коннектора Google Drive от Anthropic (который читает файлы, но не может писать в ячейки).

Типичные сценарии использования:

• Позволить Claude добавлять строки в таблицу отслеживания заявок на работу по мере подачи заявок

• Синхронизировать список литературы для чтения, еженедельный ретроспективу или журнал подготовки к IELTS

• Предоставить AI-агенту структурированный, проверяемый вывод в электронную таблицу

• Автоматизировать финансовые или операционные панели с помощью запросов на естественном языке

Возможности

• ✅ Чтение любого диапазона в нотации A1

• ✅ Обновление значений ячеек с разбором RAW или USER_ENTERED

• ✅ Добавление строк в любой лист (идеально для логирования)

• ✅ Очистка диапазонов без удаления форматирования

• ✅ Пакетное обновление нескольких диапазонов за один вызов

• ✅ Просмотр метаданных таблицы (вкладки листов, размеры)

• 🔐 OAuth 2.0 с локальным хранением токена и автоматическим обновлением

• 📦 TypeScript, ES-модули, минимальные зависимости

• 🖥️ Работает с Claude Desktop, Claude Code и любым MCP-клиентом через stdio

Быстрый запуск

# 1. Clone
git clone https://github.com/yangchoi/mcp-google-sheets.git
cd mcp-google-sheets

# 2. Install and build
npm install
npm run build

# 3. Put your Google Cloud OAuth credentials.json here
mkdir -p ~/.config/mcp-google-sheets
cp /path/to/downloaded-credentials.json ~/.config/mcp-google-sheets/credentials.json

# 4. Authorize (opens browser once)
npm run auth

# 5. Register with Claude — see below

Настройка

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

• Откройте Google Cloud Console.

• Нажмите New Project → дайте ему любое имя (например, mcp-sheets).

2. Включите Sheets API

• В вашем проекте откройте Google Sheets API.

• Нажмите Enable.

3. Создайте учетные данные OAuth 2.0

• Откройте Credentials.

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

• Если будет предложено, сначала настройте экран согласия OAuth:

  • Тип пользователя: External (если вы не находитесь в Workspace с доступным Internal)

  • Добавьте себя как тестового пользователя, пока приложение находится в режиме Testing

  • Области (scopes) можно оставить пустыми на экране согласия; приложение запросит их во время выполнения

• Вернитесь к созданию OAuth client ID:

  • Тип приложения: Desktop app

  • Имя: любое (например, mcp-google-sheets)

• Нажмите Download JSON и сохраните файл. Это ваш credentials.json.

Переместите файл в каталог конфигурации по умолчанию:

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

(Или установите GOOGLE_SHEETS_CREDENTIALS_PATH, чтобы указать другой путь — см. Конфигурация.)

4. Установите сервер

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

5. Авторизуйте

Выполните одноразовую процедуру OAuth. Откроется ваш браузер, вы разрешите доступ к своим таблицам, и полученный токен будет сохранен в ~/.config/mcp-google-sheets/token.json.

npm run auth

В терминале должно появиться сообщение Authorization complete. Token saved..

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

Claude Desktop

Отредактируйте ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) или %APPDATA%\Claude\claude_desktop_config.json (Windows) и добавьте:

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

Перезапустите Claude Desktop. Инструменты Sheets появятся в палитре инструментов.

Claude Code

Добавьте в конфигурацию MCP Claude Code (обычно ~/.claude/settings.json в разделе mcpServers):

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

Перезапустите Claude Code. Подтвердите загрузку инструментов через /mcp.

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

Все инструменты принимают spreadsheetId (находится в URL таблицы между /d/ и /edit).

Примеры использования

Подсказка Claude:

"Посмотри на таблицу 1abcXYZ... и добавь новую строку в лист Applications: Legora, Stockholm, Legal AI, 2026-08-18, pending."

Claude вызовет get_spreadsheet_metadata, чтобы найти лист, а затем append_row с этими значениями.

Или чтение + обобщение:

"Прочитай первые 20 строк листа Applications в 1abcXYZ... и скажи, сколько из них еще в статусе pending."

Claude вызовет read_range для Applications!A1:F20, а затем проанализирует полученный массив.

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

Переменные окружения (все необязательные):

Безопасность

• credentials.json и token.json хранятся только локально и никогда не передаются никуда, кроме серверов OAuth Google.

• Оба файла защищены .gitignore; не сохраняйте их в системе контроля версий.

• Сервер запрашивает только область spreadsheets — без доступа к Drive, Gmail или календарю.

• Обновление токена происходит автоматически; долгоживущий токен доступа не раскрывается.

• Работа сервера не требует открытого сетевого порта в постоянном режиме (временный порт 47319 используется только во время первоначального обратного вызова OAuth и немедленно закрывается).

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

credentials.json not found — вы пропустили шаг 3–4. Проверьте путь.

Error: access_denied во время OAuth — ваша учетная запись Google не указана как тестовый пользователь на экране согласия OAuth. Перейдите в Экран согласия OAuth → добавьте свой email в разделе Test users.

insufficient permission при вызове инструмента — токен был создан с меньшей областью видимости. Удалите token.json и повторно запустите npm run auth.

Инструмент не отображается в Claude — убедитесь, что путь в вашей конфигурации MCP абсолютный и указывает на dist/index.js (не на src/index.ts). Проверьте, что вы выполнили npm run build.

No stored token при запуске сервера — вы пропустили шаг 5. Выполните npm run auth.

Разработка

npm install
npm run dev      # tsc --watch
npm run build    # produces dist/
npm run start    # runs dist/index.js on stdio

Вклад приветствуется. Это минимальное ядро; приветствуются PR для структурных обновлений (spreadsheets.batchUpdate для форматирования, добавления листов, фильтров, защищенных диапазонов).

Лицензия

MIT