mcp-google-sheets

🤔 Что это?

mcp-google-sheets — это MCP-сервер на основе Python, который действует как мост между любым MCP-совместимым клиентом (например, Claude Desktop) и API Google Sheets. Он позволяет вам взаимодействовать с вашими Google Spreadsheets с помощью определенного набора инструментов, обеспечивая мощные рабочие процессы автоматизации и обработки данных, управляемые ИИ.

🚀 Быстрый старт (использование uvx )

По сути сервер работает в одной строке: uvx mcp-google-sheets .

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

1. ☁️ Предварительное условие: настройка Google Cloud
   • Сначала необходимо настроить учетные данные Google Cloud Platform и включить необходимые API. Мы настоятельно рекомендуем использовать учетную запись службы .
   • ➡️ Перейдите к подробному руководству по настройке Google Cloud Platform ниже.
2. 🐍 Установить uv
   • uvx является частью uv , быстрого установщика и резолвера пакетов Python. Установите его, если вы еще этого не сделали:
     # macOS / Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Windows powershell -c "irm https://astral.sh/uv/install.ps1 | iex" # Or using pip: # pip install uv
     При необходимости следуйте инструкциям в выходных данных установщика, чтобы добавить uv в PATH.
3. 🔑 Установите основные переменные среды (рекомендуется учетная запись службы)
   • Вам нужно указать серверу, как аутентифицироваться. Установите эти переменные в вашем терминале:
   • (Linux/macOS)
     # Replace with YOUR actual path and folder ID from the Google Setup step export SERVICE_ACCOUNT_PATH="/path/to/your/service-account-key.json" export DRIVE_FOLDER_ID="YOUR_DRIVE_FOLDER_ID"
   • (Команда Windows)
     set SERVICE_ACCOUNT_PATH="C:\path\to\your\service-account-key.json" set DRIVE_FOLDER_ID="YOUR_DRIVE_FOLDER_ID"
   • (Windows PowerShell)
     $env:SERVICE_ACCOUNT_PATH = "C:\path\to\your\service-account-key.json" $env:DRIVE_FOLDER_ID = "YOUR_DRIVE_FOLDER_ID"
   • ➡️ См. Подробную аутентификацию и переменные среды для других параметров (OAuth, CREDENTIALS_CONFIG ).
4. 🏃 Запустите сервер!
   • uvx автоматически загрузит и запустит последнюю версию mcp-google-sheets :
     uvx mcp-google-sheets
   • Сервер запустится и распечатает журналы, указывающие на его готовность.
5. 🔌 Подключите свой MCP-клиент
   • Настройте свой клиент (например, Claude Desktop) для подключения к работающему серверу.
   • В зависимости от используемого вами клиента, вам может не понадобиться шаг 4, поскольку клиент может запустить сервер для вас. Но это хорошая практика, чтобы в любом случае выполнить тестовый запуск шага 4, чтобы убедиться, что все настроено правильно.
   • ➡️ Примеры см. в разделе Использование с Claude Desktop .

Вы готовы! Начните отдавать команды через свой клиент MCP.

✨ Основные характеристики

• Полная интеграция: прямое подключение к API Google Диска и Google Таблиц.
• Комплексный инструментарий: предлагает широкий спектр операций (CRUD, листинг, пакетная обработка, совместное использование, форматирование и т. д.).
• Гибкая аутентификация: поддерживает учетные записи служб (рекомендуется) , OAuth 2.0 и прямое введение учетных данных через переменные среды.
• Простота развертывания: мгновенный запуск с помощью uvx (не требует установки) или клонирование для разработки с помощью uv .
• AI-Ready: разработан для использования с MCP-совместимыми клиентами, обеспечивая взаимодействие с электронными таблицами на естественном языке.

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

Этот сервер предоставляет следующие инструменты для взаимодействия с Google Таблицами:

(Входные параметры обычно представляют собой строки, если не указано иное)

• list_spreadsheets : выводит список электронных таблиц в настроенной папке Диска (учетная запись службы) или доступных пользователю (OAuth).
  • Возвращает: Список объектов [{id: string, title: string}]
• create_spreadsheet : Создает новую электронную таблицу.
  • title (строка): Желаемый заголовок.
  • Возвращает: объект с данными электронной таблицы, включая spreadsheetId .
• get_sheet_data : считывает данные из диапазона на листе.
  • spreadsheet_id (строка)
  • sheet (строка): Название листа.
  • range (необязательная строка): нотация A1 (например, 'A1:C10' , 'Sheet1!B2:D' ). Если пропущено, считывается весь лист.
  • Возвращает: двумерный массив значений ячеек.
• get_sheet_formulas : Считывает формулы из диапазона на листе.
  • spreadsheet_id (строка)
  • sheet (строка): Название листа.
  • range (необязательная строка): нотация A1 (например, 'A1:C10' , 'Sheet1!B2:D' ). Если пропущено, считывается весь лист.
  • Возвращает: двумерный массив формул ячеек.
• update_cells : Записывает данные в указанный диапазон. Перезаписывает существующие данные.
  • spreadsheet_id (строка)
  • sheet (строка)
  • range (строка): нотация A1.
  • data (двумерный массив): значения для записи.
  • Возвращает: Обновляет объект результата.
• batch_update_cells : обновляет несколько диапазонов за один вызов API.
  • spreadsheet_id (строка)
  • sheet (строка)
  • ranges (объект): Словарное отображение строк диапазонов (нотация A1) в двумерные массивы значений { "A1:B2": [[1, 2], [3, 4]], "D5": [["Hello"]] } .
  • Возвращает: объект результата пакетного обновления.
• add_rows : добавляет строки в конец листа (после последней строки с данными).
  • spreadsheet_id (строка)
  • sheet (строка)
  • data (двумерный массив): строки для добавления.
  • Возвращает: Обновляет объект результата.
• list_sheets : выводит список всех имен листов в электронной таблице.
  • spreadsheet_id (строка)
  • Возвращает: Список строк имен листов ["Sheet1", "Sheet2"] .
• create_sheet : добавляет новый лист (вкладку) в электронную таблицу.
  • spreadsheet_id (строка)
  • title (строка): Имя нового листа.
  • Возвращает: новый объект свойств листа.
• get_multiple_sheet_data : извлекает данные из нескольких диапазонов в потенциально разных электронных таблицах за один вызов.
  • queries (массив объектов): каждому объекту требуются spreadsheet_id , sheet и range . [{spreadsheet_id: 'abc', sheet: 'Sheet1', range: 'A1:B2'}, ...] .
  • Возвращает: список объектов, каждый из которых содержит параметры запроса и извлеченные data или error .
• get_multiple_spreadsheet_summary : получает заголовки, имена листов, верхние колонтитулы и первые несколько строк для нескольких электронных таблиц.
  • spreadsheet_ids (массив строк)
  • rows_to_fetch (необязательное целое число, по умолчанию 5): количество строк (включая заголовок) для предварительного просмотра.
  • Возвращает: список сводных объектов для каждой электронной таблицы.
• share_spreadsheet : предоставляет общий доступ к электронной таблице указанным пользователям/адресам электронной почты и ролям.
  • spreadsheet_id (строка)
  • recipients (массив объектов): [{email_address: 'user@example.com', role: 'writer'}, ...] . Роли: reader , commenter , writer .
  • send_notification (необязательное логическое значение, по умолчанию True): отправлять уведомления по электронной почте.
  • Возвращает: Словарь со списками successes и failures .
• add_columns : добавляет столбцы на лист. (Проверьте параметры, если они реализованы)
• copy_sheet : Дублирует лист в электронной таблице. (Проверьте параметры, если они реализованы)
• rename_sheet : переименовывает существующий лист. (Проверьте параметры, если они реализованы)

Ресурсы МКП:

• spreadsheet://{spreadsheet_id}/info : получение основных метаданных о таблице Google.
  • Возвращает: строку JSON с информацией электронной таблицы.

☁️ Настройка Google Cloud Platform (подробно)

Эту настройку необходимо выполнить перед запуском сервера.

1. Создайте/выберите проект GCP: перейдите в Google Cloud Console .
2. Включить API: Перейдите в «API и службы» -> «Библиотека». Найдите и включите:
   • Google Sheets API
   • Google Drive API
3. Настройте учетные данные: Вам необходимо выбрать один из методов аутентификации ниже (рекомендуется использовать учетную запись службы).

🔑 Аутентификация и переменные среды (подробно)

Серверу нужны учетные данные для доступа к API Google. Выберите один метод:

Метод A: Учетная запись службы (рекомендуется для серверов/автоматизации) ✅

• Почему? Безголовый (браузер не нужен), безопасный, идеально подходит для серверных сред. Не истекает быстро.
• Шаги:
  1. Создайте учетную запись службы: в консоли GCP -> «IAM и администрирование» -> «Учетные записи службы».
     • Нажмите «+ СОЗДАТЬ УЧЕТНУЮ ЗАПИСЬ СЕРВИСА». Назовите ее (например, mcp-sheets-service ).
     • Предоставление ролей: добавьте роль Editor для широкого доступа или более детализированные роли (например roles/drive.file и определенные роли Sheets) для более строгих разрешений.
     • Нажмите «Готово». Найдите учетную запись, нажмите Действия (⋮) -> «Управление ключами».
     • Нажмите «ДОБАВИТЬ КЛЮЧ» -> «Создать новый ключ» -> JSON -> «СОЗДАТЬ».
     • Загрузите и надежно сохраните файл ключа JSON.
  2. Создание и совместное использование папки Google Диска:
     • В Google Диске создайте папку (например, «AI Managed Sheets»).
     • Запишите идентификатор папки из URL-адреса: https://drive.google.com/drive/folders/THIS_IS_THE_FOLDER_ID .
     • Щелкните правой кнопкой мыши по папке -> «Поделиться» -> «Поделиться».
     • Введите адрес электронной почты учетной записи службы (из файла JSON client_email ).
     • Предоставить доступ редактора . Снимите флажок «Уведомить людей». Нажмите «Поделиться».
  3. Установите переменные среды:
     • SERVICE_ACCOUNT_PATH : Полный путь к загруженному файлу ключа JSON.
     • DRIVE_FOLDER_ID : идентификатор общей папки Google Диска. (См. Ultra Quick Start для примеров, специфичных для ОС)

Метод B: OAuth 2.0 (интерактивный / личное использование) 🧑‍💻

• Зачем? Для личного использования или локальной разработки, где интерактивный вход через браузер приемлем.
• Шаги:
  1. Настройте экран согласия OAuth: в консоли GCP -> "API и службы" -> "Экран согласия OAuth". Выберите "Внешний", заполните необходимую информацию, добавьте области действия ( .../auth/spreadsheets , .../auth/drive ), добавьте тестовых пользователей, если необходимо.
  2. Создайте идентификатор клиента OAuth: В консоли GCP -> "API и службы" -> "Учетные данные". "+ CREATE CREDENTIALS" -> "OAuth client ID" -> Тип: Desktop app . Назовите его. "CREATE". Загрузите JSON .
  3. Установите переменные среды:
     • CREDENTIALS_PATH : путь к загруженному JSON-файлу учетных данных OAuth (по умолчанию: credentials.json ).
     • TOKEN_PATH : Путь для хранения токена обновления пользователя после первого входа в систему (по умолчанию: token.json ). Должен быть доступен для записи.

Метод C: Прямое внедрение учетных данных (расширенный) 🔒

• Почему? Полезно в средах вроде Docker, Kubernetes или CI/CD, где управление файлами затруднено, но переменные среды просты/безопасны. Избегает доступа к файловой системе.
• Как? Вместо того, чтобы указывать путь к файлу учетных данных, вы указываете содержимое файла, закодированное в Base64, непосредственно в переменной среды.
• Шаги:
  1. Получите файл JSON с вашими учетными данными (ключ учетной записи службы или файл идентификатора клиента OAuth). Назовем его your_credentials.json .
  2. Сгенерируйте строку Base64:
     • (Linux/macOS): base64 -w 0 your_credentials.json
     • (Windows PowerShell):
       $filePath = "C:\path\to\your_credentials.json"; # Use actual path $bytes = [System.IO.File]::ReadAllBytes($filePath); $base64 = [System.Convert]::ToBase64String($bytes); $base64 # Copy this output
     • (Внимание): Избегайте вставки конфиденциальных учетных данных в ненадежные онлайн-кодировщики.
  3. Установите переменную среды:
     • CREDENTIALS_CONFIG : задайте для этой переменной полную строку Base64, которую вы только что сгенерировали.
       # Example (Linux/macOS) - Use the actual string generated export CREDENTIALS_CONFIG="ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb..."

Приоритет аутентификации и сводка

Сервер проверяет учетные данные в следующем порядке:

1. CREDENTIALS_CONFIG (содержимое Base64)
2. SERVICE_ACCOUNT_PATH (путь к учетной записи службы JSON)
3. CREDENTIALS_PATH (путь к OAuth JSON) — запускает интерактивный поток, если токен отсутствует или просрочен.

Краткое описание переменных среды:

⚙️ Запуск сервера (подробно)

Метод 1: Использование uvx (рекомендуется для пользователей)

Как показано в Ultra Quick Start , это самый простой способ. Установите переменные среды, затем выполните:

uvx временно обрабатывает загрузку и запуск пакета.

Метод 2: Для разработки (клонирование репозитория)

Если вы хотите изменить код:

1. Клон: git clone https://github.com/yourusername/mcp-google-sheets.git && cd mcp-google-sheets (используйте реальный URL)
2. Установите переменные среды: как описано выше.
3. Запустить с помощью uv : (использует локальный код)
   uv run mcp-google-sheets # Or via the script name if defined in pyproject.toml, e.g.: # uv run start

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

Добавьте конфигурацию сервера в claude_desktop_config.json в mcpServers . Выберите блок, соответствующий вашей настройке:

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

💬 Примеры подсказок для Клода

После подключения попробуйте выполнить следующие подсказки:

• «Перечислить все электронные таблицы, к которым у меня есть доступ» (или «в моей папке «Управляемые ИИ таблицы»)
• «Создайте новую электронную таблицу под названием «Квартальный отчет о продажах за третий квартал 2024 года».
• «В таблице «Квартальный отчет о продажах» возьмите данные из диапазона A1–E10 Листа 1».
• «Добавьте новый лист с именем «Сводка» в электронную таблицу с идентификатором 1aBcDeFgHiJkLmNoPqRsTuVwXyZ ».
• «В моей таблице «Задачи проекта», лист «Задачи», обновите ячейку B2 на «В процессе».
• «Добавьте эти строки в лист «Журнал» в электронной таблице XYZ : [['2024-07-31', 'Task A Completed'], ['2024-08-01', 'Task B Started']] »
• «Получите сводку электронных таблиц «Данные о продажах» и «Количество запасов».
• «Поделитесь таблицей «График отпусков команды» с team@example.com как читателем и manager@example.com как писателем. Не отправляйте уведомления».

🤝 Вклад

Вклады приветствуются! Пожалуйста, откройте тему, чтобы обсудить ошибки или запросы функций. Запросы на извлечение приветствуются.

📄 Лицензия

Данный проект лицензирован по лицензии MIT — подробности см. в файле LICENSE .

🙏 Кредиты

• Создано с помощью FastMCP .
• Вдохновлено kazz187/mcp-google-spreadsheet .
• Использует клиентские библиотеки Google API Python.