mcp-google-sheet

🤔 Что это такое?

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

Related MCP server: mcp-google-sheets

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

По сути, сервер запускается одной строкой: uvx mcp-google-sheets@latest.

Эта команда автоматически загрузит последнюю версию кода и запустит его. Мы рекомендуем всегда использовать @latest, чтобы у вас была самая новая версия с последними функциями и исправлениями ошибок.

Обратитесь к Руководству по идентификаторам за дополнительной информацией об используемых ниже идентификаторах.

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 CMD)

     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@latest

   • Сервер запустится и выведет в журнал сообщения о готовности.

   • 💡 Совет профессионала: Всегда используйте @latest, чтобы получить самую новую версию с исправлениями ошибок и новыми функциями. Без @latest uvx может использовать кэшированную более старую версию.

5. 🔌 Подключите ваш MCP-клиент

   • Настройте ваш клиент (например, Claude Desktop) для подключения к запущенному серверу.

   • В зависимости от используемого клиента шаг 4 может не понадобиться, поскольку клиент может запустить сервер сам. Но всё же рекомендуется проверить шаг 4, чтобы убедиться, что всё настроено правильно.

   • ➡️ См. Использование с Claude Desktop с примерами.

6. ⚡ Необязательно: включите фильтрацию инструментов (уменьшение использования контекста)

   • По умолчанию включены все 19 инструментов (~13K токенов). Чтобы уменьшить использование контекста, включите только те инструменты, которые вам нужны.

   • ➡️ См. Фильтрация инструментов для подробностей.

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

✨ Ключевые возможности

• Бесшовная интеграция: Прямое подключение к Google Drive и Google Sheets API.

• Полный набор инструментов: Широкий спектр операций (CRUD, списки, пакетные операции, предоставление доступа, форматирование и т.д.).

• Гибкая аутентификация: Поддержка сервисных аккаунтов (рекомендуется), OAuth 2.0 и прямого ввода учетных данных через переменные окружения.

• Простое развертывание: Мгновенный запуск с помощью uvx (ощущение установки без установки) или клонирование для разработки с использованием uv.

• Готовность к ИИ: Разработан для использования с MCP-совместимыми клиентами, обеспечивая взаимодействие с электронными таблицами на естественном языке.

• Фильтрация инструментов: Сокращение использования контекстного окна путём включения только нужных инструментов с помощью --include-tools или переменной окружения ENABLED_TOOLS.

🎯 Фильтрация инструментов (уменьшение использования контекста)

Проблема: По умолчанию этот MCP-сервер предоставляет все 19 инструментов, потребляя ~13 000 токенов до начала любого разговора. Если вам нужно лишь несколько инструментов, это впустую тратит ценное пространство контекстного окна.

Решение: Используйте фильтрацию инструментов, чтобы включить только те инструменты, которые вы действительно используете.

Как включить фильтрацию инструментов

Вы можете фильтровать инструменты одним из двух способов:

1. Аргумент командной строки --include-tools:

   {
     "mcpServers": {
       "google-sheets": {
         "command": "uvx",
         "args": [
           "mcp-google-sheets@latest",
           "--include-tools",
           "get_sheet_data,update_cells,list_spreadsheets,list_sheets"
         ],
         "env": {
           "SERVICE_ACCOUNT_PATH": "/path/to/credentials.json"
         }
       }
     }
   }

2. Переменная окружения ENABLED_TOOLS:

   {
     "mcpServers": {
       "google-sheets": {
         "command": "uvx",
         "args": ["mcp-google-sheets@latest"],
         "env": {
           "SERVICE_ACCOUNT_PATH": "/path/to/credentials.json",
           "ENABLED_TOOLS": "get_sheet_data,update_cells,list_spreadsheets,list_sheets"
         }
       }
     }
   }

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

При фильтрации используйте эти точные имена инструментов (через запятую, без пробелов):

Самые распространённые инструменты (рекомендуемый поднабор):

• get_sheet_data — чтение из таблиц

• update_cells — запись в таблицы

• list_spreadsheets — поиск таблиц

• list_sheets — навигация по вкладкам

Все доступные инструменты:

• add_columns

• add_rows

• batch_update

• batch_update_cells

• copy_sheet

• create_sheet

• create_spreadsheet

• find_in_spreadsheet

• get_multiple_sheet_data

• get_multiple_spreadsheet_summary

• get_sheet_data

• get_sheet_formulas

• list_folders

• list_sheets

• list_spreadsheets

• rename_sheet

• search_spreadsheets

• share_spreadsheet

• update_cells

Примечание: Если ни --include-tools, ни ENABLED_TOOLS не указаны, включены все инструменты (поведение по умолчанию).

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

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

Обратитесь к Руководству по идентификаторам за дополнительной информацией об используемых ниже идентификаторах.

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

• list_spreadsheets: Перечисляет таблицы в настроенной папке Drive (сервисный аккаунт) или доступные пользователю (OAuth).

  • folder_id (необязательная строка): Идентификатор папки Google Drive для поиска. Возьмите его из URL. Если не указан, используется настроенная папка по умолчанию или выполняется поиск в 'Мой диск'.

  • Возвращает: Список объектов [{id: string, title: string}]

• create_spreadsheet: Создаёт новую таблицу.

  • title (строка): Желаемое название таблицы. Пример: "Quarterly Report Q4".

  • folder_id (необязательная строка): Идентификатор папки Google Drive, в которой должна быть создана таблица. Возьмите его из URL. Если не указан, используется настроенная папка по умолчанию или корневая.

  • Возвращает: Объект с информацией о таблице, включая spreadsheetId, title и folder.

• get_sheet_data: Читает данные из диапазона на листе/вкладке.

  • spreadsheet_id (строка): Идентификатор таблицы (из её URL).

  • sheet (строка): Название листа/вкладки (например, "Sheet1").

  • range (необязательная строка): Нотация A1 (например, 'A1:C10', 'Sheet1!B2:D'). Если не указан, читается весь лист/вкладка, указанный в sheet.

  • include_grid_data (необязательное логическое значение, по умолчанию False): Если True, возвращаются полные данные сетки, включая форматирование и метаданные (намного больше). Если False, возвращаются только значения (эффективнее).

  • Возвращает: Если include_grid_data=True, полные данные сетки с метаданными (get response). Если False, объект результата значений из Values API (values.get response).

• get_sheet_formulas: Читает формулы из диапазона на листе/вкладке.

  • spreadsheet_id (строка): Идентификатор таблицы (из её URL).

  • sheet (строка): Название листа/вкладки (например, "Sheet1").

  • range (необязательная строка): Нотация A1 (например, 'A1:C10', 'Sheet1!B2:D'). Если не указан, читаются все формулы на листе/вкладке, указанном в sheet.

  • Возвращает: Двумерный массив формул ячеек (массив массивов) (values.get response).

• update_cells: Записывает данные в указанный диапазон. Перезаписывает существующие данные.

  • spreadsheet_id (строка): Идентификатор таблицы (из её URL).

  • sheet (строка): Название листа/вкладки (например, "Sheet1").

  • range (строка): Диапазон в нотации A1 для записи (например, 'A1:C3').

  • data (массив массивов): Двумерный массив значений для записи. Пример: [[1, 2, 3], ["a", "b", "c"]].

  • Возвращает: Объект результата обновления (values.update response).

• batch_update_cells: Обновляет несколько диапазонов за один вызов API.

  • spreadsheet_id (строка): Идентификатор таблицы (из её URL).

  • sheet (строка): Название листа/вкладки (например, "Sheet1").

  • ranges (объект): Словарь, сопоставляющий строки диапазонов (нотация A1) с двумерными массивами значений. Пример: { "A1:B2": [[1, 2], [3, 4]], "D5": [["Hello"]] }.

  • Возвращает: Результат операции (values.batchUpdate response).

• add_rows: Добавляет (вставляет) пустые строки на лист/вкладку по указанному индексу.

  • spreadsheet_id (строка): Идентификатор таблицы (из её URL).

  • sheet (строка): Название листа/вкладки (например, "Sheet1").

  • count (целое число): Количество пустых строк для вставки.

  • start_row (необязательное целое число, по умолчанию 0): Индекс строки с нуля, с которого начинается вставка строк. Если не указан, по умолчанию 0 (вставка в начало).

  • Возвращает: Результат операции (batchUpdate response).

• list_sheets: Перечисляет все названия листов/вкладок в таблице.

  • spreadsheet_id (строка): Идентификатор таблицы (из её URL).

  • Возвращает: Список строк с названиями листов/вкладок. Пример: ["Sheet1", "Sheet2"].

• create_sheet: Добавляет новый лист/вкладку в таблицу.

  • spreadsheet_id (строка): Идентификатор таблицы (из её URL).

  • title (строка): Название нового листа/вкладки.

  • Возвращает: Объект свойств нового листа.

• get_multiple_sheet_data: Получает данные из нескольких диапазонов, возможно, из разных таблиц, за один вызов.

  • queries (массив объектов): Каждый объект должен содержать spreadsheet_id, sheet и range. Пример: [{"spreadsheet_id": "abc", "sheet": "Sheet1", "range": "A1:B2"}, ...].

  • Возвращает: Список объектов, каждый из которых содержит параметры запроса и полученные data или error. Каждый data — это values.get response.

• get_multiple_spreadsheet_summary: Получает названия, имена листов/вкладок, заголовки и первые несколько строк для нескольких таблиц.

  • spreadsheet_ids (массив строк): Идентификаторы таблиц (из их URL).

  • rows_to_fetch (необязательное целое число, по умолчанию 5): Сколько строк (включая заголовок) предпросматривать. Пример: 5.

  • Возвращает: Список объектов сводки для каждой таблицы.

• share_spreadsheet: Открывает доступ к таблице указанным пользователям/электронным почтам и ролям.

  • spreadsheet_id (строка): Идентификатор таблицы (из её URL).

  • recipients (массив объектов): [{"email_address": "user@example.com", "role": "writer"}, ...]. Роли: reader, commenter, writer.

  • send_notification (необязательное логическое значение, по умолчанию True): Отправлять ли уведомления по электронной почте получателям.

  • Возвращает: Словарь со списками successes и failures.

• add_columns: Добавляет (вставляет) пустые столбцы на лист/вкладку по указанному индексу.

  • spreadsheet_id (строка): Идентификатор таблицы (из её URL).

  • sheet (строка): Название листа/вкладки (например, "Sheet1").

  • count (целое число): Количество пустых столбцов для вставки.

  • start_column (необязательное целое число, по умолчанию 0): Индекс столбца с нуля, с которого начинается вставка. Если не указан, по умолчанию 0 (вставка в начало).

  • Возвращает: Результат операции (batchUpdate response).

• copy_sheet: Дублирует лист/вкладку из одной таблицы в другую и при необходимости переименовывает его.

  • src_spreadsheet (строка): Идентификатор исходной таблицы (из её URL).

  • src_sheet (строка): Имя исходного листа/вкладки (например, "Sheet1").

  • dst_spreadsheet (строка): Идентификатор целевой таблицы (из её URL).

  • dst_sheet (строка): Желаемое имя листа/вкладки в целевой таблице.

  • Возвращает: Результат операций копирования и необязательного переименования.

• rename_sheet: Переименовывает существующий лист/вкладку.

  • spreadsheet (строка): Идентификатор таблицы (из её URL).

  • sheet (строка): Текущее имя листа/вкладки (например, "Sheet1").

  • new_name (строка): Новое имя листа/вкладки (например, "Transactions").

  • Возвращает: Результат операции (batchUpdate response).

• add_chart: Создаёт диаграмму в Google Spreadsheet на основе указанных данных.

  • spreadsheet_id (строка): Идентификатор таблицы (из её URL).

  • sheet (строка): Название листа/вкладки, содержащего данные (например, "Sheet1").

  • chart_type (строка): Тип создаваемой диаграммы. Варианты: COLUMN (вертикальные столбцы), BAR (горизонтальные столбцы), LINE, AREA, PIE, SCATTER, COMBO, HISTOGRAM.

  • data_range (строка): Диапазон в нотации A1 для данных диаграммы (например, "A1:C10"). Первая строка рассматривается как заголовки.

  • title (необязательная строка): Название диаграммы.

  • x_axis_label (необязательная строка): Подпись для оси X (нижняя ось). Не применимо для круговых диаграмм.

  • y_axis_label (необязательная строка): Подпись для оси Y (левая ось). Не применимо для круговых диаграмм.

  • position_x (необязательное целое число, по умолчанию 0): Смещение по горизонтали в пикселях от верхнего левого угла.

  • position_y (необязательное целое число, по умолчанию 0): Смещение по вертикали в пикселях от верхнего левого угла.

  • width (необязательное целое число, по умолчанию 600): Ширина диаграммы в пикселях.

  • height (необязательное целое число, по умолчанию 400): Высота диаграммы в пикселях.

  • Возвращает: Объект результата со статусом успеха, идентификатором диаграммы и деталями операции.

MCP Resources:

• spreadsheet://{spreadsheet_id}/info: Получить базовые метаданные о Google Spreadsheet.

  • Возвращает: JSON-строка с информацией о таблице.

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

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

1. Создайте/выберите проект GCP: Перейдите в Google Cloud Console.

2. Включите API: Перейдите в "APIs & Services" -> "Library". Найдите и включите:

   • Google Sheets API

   • Google Drive API

3. Настройте учётные данные: Вам нужно выбрать один из методов аутентификации ниже (рекомендуется сервисный аккаунт).

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

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

Обратитесь к Руководству по идентификаторам для получения дополнительной информации об идентификаторах, используемых ниже.

Метод A: Сервисный аккаунт (рекомендуется для серверов/автоматизации) ✅

• Почему? Безголовый (не нужен браузер), безопасный, идеален для серверных сред. Не истекает легко.

• Шаги:

  1. Создайте сервисный аккаунт: В GCP Console -> "IAM & Admin" -> "Service Accounts".

     • Нажмите "+ CREATE SERVICE ACCOUNT". Дайте ему имя (например, mcp-sheets-service).

     • Назначьте роли: добавьте роль Editor для широкого доступа или более детальные роли (например, roles/drive.file и конкретные роли Sheets) для более строгих разрешений.

     • Нажмите "Done". Найдите аккаунт, нажмите "Actions" (⋮) -> "Manage keys".

     • Нажмите "ADD KEY" -> "Create new key" -> JSON -> "CREATE".

     • Скачайте и безопасно храните файл ключа JSON.

  2. Создайте и предоставьте доступ к папке Google Drive:

     • В Google Drive создайте папку (например, "AI Managed Sheets").

     • Запишите идентификатор папки из URL: https://drive.google.com/drive/folders/THIS_IS_THE_FOLDER_ID.

     • Щёлкните правой кнопкой мыши по папке -> "Share" -> "Share".

     • Введите адрес электронной почты сервисного аккаунта (из JSON-файла client_email).

     • Предоставьте доступ Editor. Снимите флажок "Notify people". Нажмите "Share".

  3. Установите переменные окружения:

     • SERVICE_ACCOUNT_PATH: Полный путь к скачанному файлу ключа JSON.

     • DRIVE_FOLDER_ID: Идентификатор общей папки Google Drive. (См. Ultra Quick Start для примеров для конкретных ОС)

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

• Почему? Для личного использования или локальной разработки, где допустим интерактивный вход через браузер.

• Шаги:

  1. Настройте экран согласия OAuth: В GCP Console -> "APIs & Services" -> "OAuth consent screen". Выберите "External", заполните необходимую информацию, добавьте области (.../auth/spreadsheets, .../auth/drive), при необходимости добавьте тестовых пользователей.

  2. Создайте OAuth Client ID: В GCP Console -> "APIs & Services" -> "Credentials". "+ 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 Client ID). Назовем его 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..."

Метод D: Учетные данные приложения по умолчанию (ADC) 🌐

• Зачем? Идеально подходит для сред Google Cloud (GKE, Compute Engine, Cloud Run) и локальной разработки с gcloud auth application-default login. Явные файлы учетных данных не требуются.

• Как? Использует цепочку стандартных учетных данных приложения Google для автоматического обнаружения учетных данных из нескольких источников.

• Порядок поиска ADC:

  1. Переменная окружения GOOGLE_APPLICATION_CREDENTIALS (путь к ключу сервисного аккаунта) — стандартная переменная Google

  2. Учетные данные gcloud auth application-default login (локальная разработка)

  3. Привязанный сервисный аккаунт с сервера метаданных (GKE, Compute Engine и т. д.)

• Настройка:

  • Локальная разработка:

    1. Выполните gcloud auth application-default login --scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/spreadsheets,https://www.googleapis.com/auth/drive один раз

    2. Задайте квотный проект: gcloud auth application-default set-quota-project <project_id> (замените <project_id> на ID вашего проекта Google Cloud)

  • Google Cloud: привяжите сервисный аккаунт к вашему вычислительному ресурсу

  • Переменная окружения: задайте GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json (стандартная переменная Google)

• Дополнительные переменные окружения не требуются — ADC используется автоматически как запасной вариант, когда другие методы не срабатывают.

Примечание: GOOGLE_APPLICATION_CREDENTIALS — это официальная стандартная переменная окружения Google, а SERVICE_ACCOUNT_PATH специфична для этого MCP-сервера. Если вы зададите GOOGLE_APPLICATION_CREDENTIALS, ADC найдет ее автоматически.

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

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

1. CREDENTIALS_CONFIG (содержимое в Base64)

2. SERVICE_ACCOUNT_PATH (путь к JSON сервисного аккаунта)

3. CREDENTIALS_PATH (путь к OAuth JSON) — запускает интерактивный процесс, если токен отсутствует или истек

4. Учетные данные приложения по умолчанию (ADC) — автоматический запасной вариант

Сводка переменных окружения:

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

Обратитесь к Справочнику по ID для получения информации об ID, используемых ниже.

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

Как показано в Ультра-быстром старте, это самый простой способ. Задайте переменные окружения, затем выполните:

uvx mcp-google-sheets@latest

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

Метод 3: Docker (транспорт SSE)

Запустите сервер в контейнере, используя прилагаемый Dockerfile:

# Build the image
docker build -t mcp-google-sheets .

# Run (SSE on port 8000)
# NOTE: Prefer CREDENTIALS_CONFIG (Base64 credentials content) in containers.
docker run --rm -p 8000:8000 ^
  -e HOST=0.0.0.0 ^
  -e PORT=8000 ^
  -e CREDENTIALS_CONFIG=YOUR_BASE64_CREDENTIALS ^
  -e DRIVE_FOLDER_ID=YOUR_DRIVE_FOLDER_ID ^
  mcp-google-sheets

• Используйте CREDENTIALS_CONFIG вместо SERVICE_ACCOUNT_PATH внутри Docker, чтобы не монтировать секреты как файлы.

• Контейнер запускается с флагом --transport sse и прослушивает HOST/PORT. Подключайте ваш MCP-клиент к http://localhost:8000 через транспорт SSE.

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

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

Обратитесь к Справочнику по ID для получения информации об ID, используемых ниже.

⚠️ Важные примечания:

• 🍎 Пользователи macOS: используйте полный путь: "/Users/yourusername/.local/bin/uvx" вместо просто "uvx"

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {
        "SERVICE_ACCOUNT_PATH": "/full/path/to/your/service-account-key.json",
        "DRIVE_FOLDER_ID": "your_shared_folder_id_here"
      }
    }
  }
}

🍎 Примечание для macOS: Если вы получаете ошибку spawn uvx ENOENT, используйте полный путь к uvx:

{
  "mcpServers": {
    "google-sheets": {
      "command": "/Users/yourusername/.local/bin/uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {
        "SERVICE_ACCOUNT_PATH": "/full/path/to/your/service-account-key.json",
        "DRIVE_FOLDER_ID": "your_shared_folder_id_here"
      }
    }
  }
}

Замените yourusername на ваше реальное имя пользователя.

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {
        "CREDENTIALS_PATH": "/full/path/to/your/credentials.json",
        "TOKEN_PATH": "/full/path/to/your/token.json"
      }
    }
  }
}

Примечание: при первом использовании может открыться браузер для входа в Google. Убедитесь, что TOKEN_PATH доступен для записи.

🍎 Примечание для macOS: Если вы получаете ошибку spawn uvx ENOENT, замените "command": "uvx" на "command": "/Users/yourusername/.local/bin/uvx" (замените yourusername на ваше реальное имя пользователя).

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {
        "CREDENTIALS_CONFIG": "ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb3VudCIsCiAgInByb2plY3RfaWQiOiAi...",
        "DRIVE_FOLDER_ID": "your_shared_folder_id_here"
      }
    }
  }
}

Примечание: вставьте полную строку Base64 для CREDENTIALS_CONFIG. DRIVE_FOLDER_ID по-прежнему требуется для контекста папки сервисного аккаунта.

🍎 Примечание для macOS: Если вы получаете ошибку spawn uvx ENOENT, замените "command": "uvx" на "command": "/Users/yourusername/.local/bin/uvx" (замените yourusername на ваше реальное имя пользователя).

Вариант 1: с GOOGLE_APPLICATION_CREDENTIALS

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json"
      }
    }
  }
}

Вариант 2: с gcloud auth (переменные окружения не нужны)

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {}
    }
  }
}

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

1. Сначала выполните gcloud auth application-default login --scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/spreadsheets,https://www.googleapis.com/auth/drive.

2. Задайте квотный проект: gcloud auth application-default set-quota-project <project_id>

🍎 Примечание для macOS: Если вы получаете ошибку spawn uvx ENOENT, замените "command": "uvx" на "command": "/Users/yourusername/.local/bin/uvx" (замените yourusername на ваше реальное имя пользователя).

{
  "mcpServers": {
    "mcp-google-sheets-local": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/your/mcp-google-sheets",
        "mcp-google-sheets"
      ],
      "env": {
        "SERVICE_ACCOUNT_PATH": "/path/to/your/mcp-google-sheets/service_account.json",
        "DRIVE_FOLDER_ID": "your_drive_folder_id_here"
      }
    }
  }
}

Примечание: используйте флаг --directory для указания пути к проекту и скорректируйте пути в соответствии с вашим реальным расположением рабочей области.

💬 Примеры запросов для Claude

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

• "Перечисли все таблицы, к которым у меня есть доступ." (или "в моей папке AI Managed Sheets")

• "Создай новую таблицу с названием 'Quarterly Sales Report Q3 2024'."

• "В таблице 'Quarterly Sales Report' получи данные из Sheet1 в диапазоне A1:E10."

• "Добавь новый лист с названием 'Summary' в таблицу с ID 1aBcDeFgHiJkLmNoPqRsTuVwXyZ."

• "В моей таблице 'Project Tasks', на листе 'Tasks', обнови ячейку B2 на 'In Progress'."

• "Добавь эти строки на лист 'Log' в таблице XYZ: [['2024-07-31', 'Task A Completed'], ['2024-08-01', 'Task B Started']]"

• "Получи сводку по таблицам 'Sales Data' и 'Inventory Count'."

• "Открой доступ к таблице 'Team Vacation Schedule' для team@example.com с правами читателя и для manager@example.com с правами редактора. Не отправляй уведомления."

• "Создай столбчатую диаграмму в моей таблице 'Sales Report', показывающую ежемесячную выручку из данных в диапазоне A1:B13."

• "Добавь круговую диаграмму на лист 'Market Analysis' с данными из A1:B5 и заголовком 'Market Share by Product'."

• "В таблице abc123 создай линейную диаграмму на Sheet1 из диапазона A1:C10 с заголовком 'Growth Trends' и подписями 'Month' и 'Revenue'."

🆔 Справочник по ID

Используйте следующий справочник, чтобы найти различные ID, упоминаемые в документации:

Google Cloud Project ID:
  https://console.cloud.google.com/apis/dashboard?project=sheets-mcp-server-123456
                                                          └───── Project ID ─────┘

Google Drive Folder ID:
  https://drive.google.com/drive/u/0/folders/1xcRQCU9xrNVBPTeNzHqx4hrG7yR91WIa
                                             └────────── Folder ID ──────────┘

Google Sheets Spreadsheet ID:
  https://docs.google.com/spreadsheets/d/25_-_raTaKjaVxu9nJzA7-FCrNhnkd3cXC54BPAOXemI/edit
                                         └───────────── Spreadsheet ID ─────────────┘

🤝 Участие в разработке

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

📄 Лицензия

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

🙏 Благодарности

• Создано с помощью FastMCP.

• Вдохновлено kazz187/mcp-google-spreadsheet.

• Использует клиентские библиотеки Google API Python.