Google Sheets MCP Server

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

Инструменты

Во всех инструментах spreadsheet — это ID таблицы или её полная ссылка, sheet — название листа (по умолчанию первый).

Related MCP server: google-sheets-mcp

Настройка Google

1. Откройте Google Cloud Console и создайте проект (или выберите существующий).

2. Включите оба API — по умолчанию в новом проекте они выключены, и без них сервер работать не будет:

   • Google Sheets API — чтение и запись данных, работа с листами;

   • Google Drive API — список таблиц, создание и выдача доступа.

   Перейдите по каждой ссылке, убедитесь, что вверху выбран нужный проект, и нажмите Enable (Включить). То же самое можно сделать через APIs & Services → Library. После включения подождите 1–5 минут, пока изменение применится.

3. APIs & Services → Credentials → Create credentials → Service account. Создайте аккаунт, роли можно не назначать.

4. Откройте созданный сервисный аккаунт → Keys → Add key → Create new key → JSON и сохраните файл, например как service_account.json в корне проекта.

5. Скопируйте email сервисного аккаунта (вида name@project.iam.gserviceaccount.com) и откройте ему доступ к нужным таблицам через кнопку «Настройки доступа», как обычному пользователю.

Сервисный аккаунт видит только таблицы, которыми с ним поделились, и те, что создал сам.

Ограничение на создание таблиц. У новых сервисных аккаунтов квота Google Drive равна 0, поэтому create_spreadsheet вернёт ошибку «storage quota exceeded». В этом случае создайте таблицу вручную и откройте к ней доступ для сервисного аккаунта — все остальные инструменты работают. Создание работает, если у аккаунта есть квота (например, в Google Workspace с общими дисками).

Частые ошибки

⚠️ Никогда не коммитьте JSON-ключ. Файлы service_account*.json, credentials*.json и .env уже добавлены в .gitignore.

Ниже /path/to/google-sheets-mcp — путь к папке проекта, /path/to/service_account.json — путь к ключу. На Windows используйте пути вида C:\path\to\..., а в JSON экранируйте обратные слэши: C:\\path\\to\\....

Вариант 1: локально (Python)

Требуется Python 3.10+.

git clone https://github.com/zeegbee/google-sheets-mcp.git
cd google-sheets-mcp
python -m venv .venv

# Linux / macOS
.venv/bin/pip install -r requirements.txt
# Windows
.venv\Scripts\pip install -r requirements.txt

Claude Code

claude mcp add google-sheets \
  -e GOOGLE_SERVICE_ACCOUNT_FILE=/path/to/service_account.json \
  -- /path/to/google-sheets-mcp/.venv/bin/python /path/to/google-sheets-mcp/server.py

На Windows интерпретатор лежит в .venv\Scripts\python.exe.

Claude Desktop

Добавьте в конфиг (%APPDATA%\Claude\claude_desktop_config.json на Windows, ~/Library/Application Support/Claude/claude_desktop_config.json на macOS):

{
  "mcpServers": {
    "google-sheets": {
      "command": "/path/to/google-sheets-mcp/.venv/bin/python",
      "args": ["/path/to/google-sheets-mcp/server.py"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_FILE": "/path/to/service_account.json"
      }
    }
  }
}

и перезапустите Claude Desktop.

Вариант 2: Docker

Python ставить не нужно, достаточно Docker.

git clone https://github.com/zeegbee/google-sheets-mcp.git
cd google-sheets-mcp
docker build -t google-sheets-mcp .

Ключ в образ не попадает — он монтируется при запуске в /secrets/service_account.json (только для чтения). MCP общается через stdin/stdout, поэтому обязателен флаг -i. Контейнер запускает сам MCP-клиент, вручную держать его запущенным не нужно.

Claude Code

claude mcp add google-sheets -- docker run -i --rm \
  -v /path/to/service_account.json:/secrets/service_account.json:ro \
  google-sheets-mcp

Claude Desktop

{
  "mcpServers": {
    "google-sheets": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/path/to/service_account.json:/secrets/service_account.json:ro",
        "google-sheets-mcp"
      ]
    }
  }
}

Docker Desktop должен быть запущен до старта Claude.

Проверка

Smoke-тест проверяет, что сервер стартует, отдаёт все инструменты и корректно сообщает об отсутствии ключа (сам ключ не нужен):

python tests/smoke_test.py                                    # локально
python tests/smoke_test.py docker run -i --rm google-sheets-mcp  # в Docker

Тот же тест запускается в GitHub Actions на каждый push и pull request.

Интерактивно проверить инструменты можно через MCP Inspector (нужен Node.js):

GOOGLE_SERVICE_ACCOUNT_FILE=/path/to/service_account.json \
  npx @modelcontextprotocol/inspector .venv/bin/python server.py

Примеры запросов к Claude:

• «Покажи, какие таблицы мне доступны»

• «Создай таблицу "Бюджет" и открой доступ на me@example.com»

• «Прочитай лист "Продажи" из https://docs.google.com/spreadsheets/d/... и посчитай итог»

• «Добавь в конец строку: 2026-10-01, Кофе, 350»

Веб-интерфейс

В examples/web-viewer — пример веб-интерфейса для просмотра таблиц в браузере. Он подключается к этому серверу как MCP-клиент (локально или через Docker):

cd examples/web-viewer
../../.venv/bin/python app.py            # Windows: ..\..\.venv\Scripts\python app.py
../../.venv/bin/python app.py --docker   # сервер в Docker-образе google-sheets-mcp

Подробности — в README примера.

Структура проекта

├── server.py              # MCP-сервер
├── requirements.txt       # зависимости
├── Dockerfile
├── tests/smoke_test.py    # smoke-тест по протоколу MCP
├── examples/web-viewer/   # пример: веб-интерфейс на MCP-клиенте
├── .github/workflows/     # CI: тесты на Python 3.10 и 3.13, Docker-образ, веб-интерфейс
└── .env.example           # пример переменных окружения

Лицензия

MIT