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. 🐍 Установить

   • 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

     При необходимости следуйте инструкциям в выходных данных установщика, чтобы добавить

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 Диска. (См.

Метод 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 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.