{"_id":"@a1-x-tech/mcp-google-sheets","name":"@a1-x-tech/mcp-google-sheets","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@a1-x-tech/mcp-google-sheets","version":"0.1.0","description":"MCP server for the Google Sheets API — search spreadsheets, read and write ranges, manage sheets, formatting, validation, protected ranges, tables, charts and sharing. For Claude, Cursor, Codex and other AI clients.","mcpName":"io.github.A1-x-Tech/mcp-google-sheets","type":"module","bin":{"mcp-google-sheets":"dist/index.js"},"engines":{"node":">=20"},"publishConfig":{"access":"public"},"scripts":{"build":"rm -rf dist && tsc","start":"node dist/index.js","dev":"tsx watch src/index.ts","typecheck":"tsc -p tsconfig.check.json","smoke":"node --import tsx src/smoke.ts","test":"npm run test:src && npm run test:dist","test:src":"node --import tsx --test $(find src -name '*.test.ts')","test:dist":"npm run build && node --test test/dist-smoke.test.js","prepare":"npm run build","prepublishOnly":"npm run typecheck && npm test"},"keywords":["mcp","model-context-protocol","google","google-sheets","sheets","spreadsheet","excel","claude","cursor","codex"],"license":"MIT","author":{"name":"gistrec","email":"gistrec@gmail.com"},"repository":{"type":"git","url":"git+https://github.com/A1-x-Tech/mcp-google-sheets.git"},"homepage":"https://github.com/A1-x-Tech/mcp-google-sheets#readme","bugs":{"url":"https://github.com/A1-x-Tech/mcp-google-sheets/issues"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","zod":"^3.25.0"},"devDependencies":{"@types/node":"^25.9.3","tsx":"^4.22.4","typescript":"^5.7.0"},"gitHead":"7cb029738e221cd623707a968bba60a3d028b308","_id":"@a1-x-tech/mcp-google-sheets@0.1.0","_nodeVersion":"24.15.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-X36QaC5oLPs8MgYcZsedich4k5+m6D6P8bUvnhOwZGsfw+54MU0YcVbGfcPIaRANo2bEctNHBmo8CLTYo0y/ig==","shasum":"37bc466ebffcd92a29604576cf4dafed0e8743c7","tarball":"https://registry.npmjs.org/@a1-x-tech/mcp-google-sheets/-/mcp-google-sheets-0.1.0.tgz","fileCount":19,"unpackedSize":155856,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDW1IPj0Tbd1mDjbefOR8IGN5+y3uYPggyrGrUgxsUuAgIhAMVRWz5CQCSpoblcVy+JMOw+YO1q3hdYpWo7+03kMC1q"}]},"_npmUser":{"name":"gistrec","email":"gistrec@gmail.com"},"directories":{},"maintainers":[{"name":"gistrec","email":"gistrec@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-google-sheets_0.1.0_1788054551674_0.06515213160536892"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-30T01:49:11.450Z","0.1.0":"2026-08-30T01:49:11.801Z","modified":"2026-08-30T01:49:12.036Z"},"maintainers":[{"name":"gistrec","email":"gistrec@gmail.com"}],"description":"MCP server for the Google Sheets API — search spreadsheets, read and write ranges, manage sheets, formatting, validation, protected ranges, tables, charts and sharing. For Claude, Cursor, Codex and other AI clients.","homepage":"https://github.com/A1-x-Tech/mcp-google-sheets#readme","keywords":["mcp","model-context-protocol","google","google-sheets","sheets","spreadsheet","excel","claude","cursor","codex"],"repository":{"type":"git","url":"git+https://github.com/A1-x-Tech/mcp-google-sheets.git"},"author":{"name":"gistrec","email":"gistrec@gmail.com"},"bugs":{"url":"https://github.com/A1-x-Tech/mcp-google-sheets/issues"},"license":"MIT","readme":"# <img src=\"./assets/a1-logo.svg\" alt=\"A1\" width=\"40\"> Google Sheets MCP\n\n[English](./README.md) | **Русский**\n\n[![npm](https://img.shields.io/npm/v/%40a1-x-tech%2Fmcp-google-sheets)](https://www.npmjs.com/package/@a1-x-tech/mcp-google-sheets)\n[![CI](https://github.com/A1-x-Tech/mcp-google-sheets/actions/workflows/ci.yml/badge.svg)](https://github.com/A1-x-Tech/mcp-google-sheets/actions/workflows/ci.yml)\n[![Glama](https://glama.ai/mcp/servers/A1-x-Tech/mcp-google-sheets/badges/score.svg)](https://glama.ai/mcp/servers/A1-x-Tech/mcp-google-sheets)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n\n**A1 Google Sheets MCP** позволяет AI-приложению работать с Google Sheets на естественном языке. Можно найти таблицу, прочитать данные, записать и дописать строки, настроить листы и форматирование, построить диаграммы и поделиться результатом.\n\nСервер работает с Google Sheets API через ваш Google-аккаунт. Он разделяет чтение и запись, явно помечает разрушительные операции и честно показывает ограничения Sheets API, а не создаёт впечатление, что с таблицей можно сделать всё.\n\n- **20 инструментов.** Поиск и создание таблиц, чтение и запись диапазонов, управление листами, форматированием, проверкой данных, защищёнными диапазонами, условным форматированием, структурированными таблицами, диаграммами и доступом.\n- **Осознанная запись.** Запись никогда не повторяется после неопределённой ошибки — повтор `append` продублировал бы строки, — а разрушительные инструменты помечены, чтобы AI-клиент мог сначала спросить.\n- **Только Sheets.** Drive — внутренняя зависимость лишь для поиска таблиц и управления доступом; отдельного Drive-инструмента нет, и `raw_request` до Drive не дотягивается.\n- **Минимальные scope Google.** `spreadsheets` покрывает каждый Sheets-инструмент; scope Drive нужен только для поиска таблиц и управления доступом.\n\nНачните с запроса, который только читает данные:\n\n> Найди таблицу с квартальным бюджетом и кратко расскажи, что на каждом её листе.\n\n[Подключить сервер](#быстрый-старт) · [Посмотреть сценарии](#что-можно-поручить) · [Открыть техническую документацию](#техническая-документация)\n\n---\n\n## Увидеть работу за минуту\n\n> **Вы:** Покажи структуру таблицы с отчётом о продажах: листы, их размеры и закреплённые строки.\n>\n> **Ассистент:** Показывает листы, их размеры, закреплённые заголовки и объекты на них. Ничего не меняется.\n>\n> **Вы:** Подготовь лист «Март» как копию «Февраля» и очисти цифры, сохранив оформление.\n>\n> **Ассистент:** Показывает план — продублировать лист, переименовать его и очистить диапазоны с данными — и запрашивает подтверждение перед любым изменением.\n>\n> **Вы:** Подтверждаю.\n>\n> **Ассистент:** Дублирует лист и очищает значения. Форматирование, проверка данных и закреплённые строки остаются.\n\n## Содержание\n\n- [Быстрый старт](#быстрый-старт)\n- [Что можно поручить](#что-можно-поручить)\n- [Как меняется таблица](#как-меняется-таблица)\n- [Что может измениться](#что-может-измениться)\n- [Как получить доступ](#как-получить-доступ)\n- [Конфигурация](#конфигурация)\n- [Данные, лимиты и работа в фоне](#данные-лимиты-и-работа-в-фоне)\n- [Техническая документация](#техническая-документация)\n- [Поддержка](#поддержка)\n\n## Быстрый старт\n\nНужны Node.js 20+, Google-аккаунт и OAuth-данные из проекта Google Cloud с включённым Google Sheets API.\n\n1. [Подготовьте Google OAuth-доступ](#как-получить-доступ).\n2. Добавьте сервер в AI-приложение.\n3. Отправьте запрос, который только читает данные.\n\n<details open>\n<summary><strong>Codex</strong></summary>\n\n<br>\n\n**В приложении:** откройте **Settings → Plugins → MCP servers**, нажмите **Add server**, затем добавьте `npx -y @a1-x-tech/mcp-google-sheets@latest` с `GOOGLE_SHEETS_CLIENT_ID`, `GOOGLE_SHEETS_CLIENT_SECRET` и `GOOGLE_SHEETS_REFRESH_TOKEN`.\n\n**В командной строке:**\n\n```bash\ncodex mcp add google-sheets \\\n  --env GOOGLE_SHEETS_CLIENT_ID=your_client_id \\\n  --env GOOGLE_SHEETS_CLIENT_SECRET=your_client_secret \\\n  --env GOOGLE_SHEETS_REFRESH_TOKEN=your_refresh_token \\\n  -- npx -y @a1-x-tech/mcp-google-sheets@latest\n```\n\n```bash\ncodex mcp list\n```\n\n[Документация Codex MCP](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)\n\n</details>\n\n<details>\n<summary><strong>Claude Code</strong></summary>\n\n<br>\n\n```bash\nclaude mcp add \\\n  --env GOOGLE_SHEETS_CLIENT_ID=your_client_id \\\n  --env GOOGLE_SHEETS_CLIENT_SECRET=your_client_secret \\\n  --env GOOGLE_SHEETS_REFRESH_TOKEN=your_refresh_token \\\n  --transport stdio --scope user google-sheets \\\n  -- npx -y @a1-x-tech/mcp-google-sheets@latest\n```\n\n```bash\nclaude mcp list\n```\n\n[Документация Claude Code MCP](https://code.claude.com/docs/en/mcp)\n\n</details>\n\n<details>\n<summary><strong>Claude Desktop</strong></summary>\n\n<br>\n\nОткройте **Settings → Developer → Edit Config** и добавьте:\n\n```json\n{\n  \"mcpServers\": {\n    \"google-sheets\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@a1-x-tech/mcp-google-sheets@latest\"],\n      \"env\": {\n        \"GOOGLE_SHEETS_CLIENT_ID\": \"your_client_id\",\n        \"GOOGLE_SHEETS_CLIENT_SECRET\": \"your_client_secret\",\n        \"GOOGLE_SHEETS_REFRESH_TOKEN\": \"your_refresh_token\"\n      }\n    }\n  }\n}\n```\n\nЕсли **Edit Config** недоступна, отредактируйте `~/Library/Application Support/Claude/claude_desktop_config.json` на macOS или `%APPDATA%\\Claude\\claude_desktop_config.json` на Windows.\n\n[Документация Claude Desktop MCP](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop)\n\n</details>\n\n<details>\n<summary><strong>Cursor</strong></summary>\n\n<br>\n\nДобавьте в `~/.cursor/mcp.json` на macOS/Linux или `%USERPROFILE%\\.cursor\\mcp.json` на Windows:\n\n```json\n{\n  \"mcpServers\": {\n    \"google-sheets\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@a1-x-tech/mcp-google-sheets@latest\"],\n      \"env\": {\n        \"GOOGLE_SHEETS_CLIENT_ID\": \"your_client_id\",\n        \"GOOGLE_SHEETS_CLIENT_SECRET\": \"your_client_secret\",\n        \"GOOGLE_SHEETS_REFRESH_TOKEN\": \"your_refresh_token\"\n      }\n    }\n  }\n}\n```\n\n[Документация Cursor MCP](https://cursor.com/docs/mcp)\n\n</details>\n\n<details>\n<summary><strong>VS Code</strong></summary>\n\n<br>\n\nЗапустите **MCP: Open User Configuration** и добавьте:\n\n```json\n{\n  \"servers\": {\n    \"google-sheets\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@a1-x-tech/mcp-google-sheets@latest\"],\n      \"env\": {\n        \"GOOGLE_SHEETS_CLIENT_ID\": \"${input:sheets_client_id}\",\n        \"GOOGLE_SHEETS_CLIENT_SECRET\": \"${input:sheets_client_secret}\",\n        \"GOOGLE_SHEETS_REFRESH_TOKEN\": \"${input:sheets_refresh_token}\"\n      }\n    }\n  },\n  \"inputs\": [\n    { \"type\": \"promptString\", \"id\": \"sheets_client_id\", \"description\": \"Google OAuth client ID\" },\n    { \"type\": \"promptString\", \"id\": \"sheets_client_secret\", \"description\": \"Google OAuth client secret\", \"password\": true },\n    { \"type\": \"promptString\", \"id\": \"sheets_refresh_token\", \"description\": \"Google OAuth refresh token\", \"password\": true }\n  ]\n}\n```\n\nПроверьте сервер командой **MCP: List Servers**.\n\n[Документация VS Code MCP](https://code.visualstudio.com/docs/agent-customization/mcp-servers)\n\n</details>\n\n## Что можно поручить\n\n### Найти и прочитать данные\n\n- Найди самую свежую таблицу со словом «бюджет» в названии и покажи её структуру.\n- Прочитай `'Q3'!A1:F50` и суммируй итоги.\n- Покажи формулы, по которым считается лист «Итоги».\n\n### Обновить цифры\n\n- Запиши эту таблицу в `Sheet1!A1` вместе с формулами.\n- Добавь сегодняшние показатели новой строкой журнала.\n- Обнови несколько диапазонов одним пакетом или очисти черновой диапазон, сохранив его оформление.\n\n### Оформить и показать\n\n- Добавь лист «Март», закрепи строку заголовка и выдели её жирным.\n- Подсвети отрицательные суммы красным условным форматом и добавь границы.\n- Построй столбчатую диаграмму выручки по месяцам на отдельном листе.\n- Преврати данные в структурированную таблицу и добавь выпадающий список через проверку данных.\n\n### Защитить и поделиться\n\n- Защити строку итогов, чтобы её мог менять только я.\n- Дай коллеге право редактирования, а остальным — только чтение.\n- Покажи, у кого сейчас есть доступ к файлу.\n\n## Как меняется таблица\n\n1. Инструменты значений адресуют ячейки в **нотации A1** (`'Имя листа'!A1:C10`); структурные инструменты (листы, форматирование, правила, таблицы, диаграммы) адресуют числовой **sheetId** и индексы с отсчётом от нуля. Идентификаторы даёт `get_spreadsheet` — названия листов адресами не являются.\n2. Запись **перезаписывает** свой диапазон; `append_values` добавляет строки после последней строки данных; ячейка `null` пропускается, а не очищается.\n3. `clear_values` очищает значения и формулы, но сохраняет форматирование, проверку данных, заметки и объединения. Отмены через API нет — удаление листа, строк или столбцов уничтожает их данные.\n4. Пакетные инструменты переносят несколько диапазонов или запросов одним вызовом и считаются в квоте один раз; `batchUpdate` атомарен — применяются все его запросы или ни один.\n\nУ части возможностей таблиц нет отдельного инструмента: объединённые ячейки, именованные диапазоны, чередование цветов, фильтры, срезы, поиск с заменой и градиентные правила условного форматирования доступны через `raw_request`, который ограничен доменом Sheets API. Новая таблица создаётся в корне My Drive — перенос в папку сервер не покрывает, а `manage_permissions` не передаёт владение файлом.\n\n## Что может измениться\n\n| Операция | Что происходит | Граница подтверждения |\n|---|---|---|\n| Чтение метаданных и значений | Читает структуру и ячейки | Ничего не меняет |\n| Создание таблицы | Добавляет файл в My Drive | Меняет Google Sheets |\n| Запись, пакетная запись или добавление значений | Перезаписывает ячейки или добавляет строки | Меняет таблицу |\n| Форматирование, закрепление, границы, строки и столбцы, проверка данных, правила, таблицы, диаграммы | Меняет оформление, структуру и правила | Меняет таблицу |\n| Очистка значений, удаление листа, строк или столбцов | Удаляет данные без отмены через API | Разрушительно |\n| Управление защищёнными диапазонами и доступом | Меняет, кто может открывать и редактировать файл | Меняет доступ |\n| Технический запрос API | Может вызвать метод API без отдельного инструмента | Потенциально разрушительно |\n\nКак AI-приложение просит подтверждение, определяет само приложение. Сервер помечает операции чтения, записи и удаления, чтобы оно отличило проверку от рабочего изменения.\n\n## Как получить доступ\n\nДля редактирования таблиц Google Sheets требует OAuth 2.0: одного API-ключа недостаточно.\n\n1. Создайте или выберите проект Google Cloud и включите **Google Sheets API**. Включите также **Google Drive API**, если нужны поиск таблиц и управление доступом.\n2. Настройте OAuth consent screen и создайте OAuth-клиент типа **Desktop app**.\n3. Авторизуйте Google-аккаунт, который владеет таблицами или может их редактировать. [OAuth 2.0 Playground](https://developers.google.com/oauthplayground) поможет получить refresh token, если включить **Use your own OAuth credentials**.\n4. Запросите минимальный scope:\n\n   ```text\n   https://www.googleapis.com/auth/spreadsheets\n   ```\n\n   Он покрывает каждый Sheets-инструмент. Дополнительный scope Drive нужен только `search_spreadsheets` и `manage_permissions`: `https://www.googleapis.com/auth/drive`, либо `drive.readonly` только для поиска, либо `drive.file` для файлов, созданных через это приложение.\n\nRefresh token OAuth-приложения в режиме Testing может истечь через семь дней. Для долгого доступа опубликуйте OAuth-приложение или используйте Internal-приложение в домене Workspace. Храните client secret и refresh token как пароли.\n\n## Конфигурация\n\n| Переменная | Обязательна | Описание |\n|---|---|---|\n| `GOOGLE_SHEETS_CLIENT_ID` | Да* | OAuth client ID. |\n| `GOOGLE_SHEETS_CLIENT_SECRET` | Да* | OAuth client secret. |\n| `GOOGLE_SHEETS_REFRESH_TOKEN` | Да* | OAuth refresh token. |\n| `GOOGLE_SHEETS_ACCESS_TOKEN` | Да* | Короткоживущая (~1 ч) альтернатива OAuth-тройке. |\n| `GOOGLE_SHEETS_API_BASE` | Нет | Переопределяет базовый URL Google Sheets API. |\n| `GOOGLE_SHEETS_TIMEOUT_MS` | Нет | Тайм-аут одного запроса; по умолчанию `60000` мс. |\n| `GOOGLE_SHEETS_MAX_RETRIES` | Нет | Повторы временных ошибок; по умолчанию `3`. |\n\n\\* Передайте OAuth-тройку или access token. Без учётных данных сервер всё равно запустится и покажет инструменты; первый вызов назовёт переменные, которые нужно задать.\n\n## Данные, лимиты и работа в фоне\n\n- **Запросы идут в Google.** Локальный сервер обновляет OAuth-токены Google и вызывает Sheets API, а для поиска таблиц и управления доступом — Drive API. Анонимная телеметрия содержит ID установки, версию пакета, версии AI-клиента и платформы и имена инструментов — но не OAuth-токены, данные таблиц, аргументы или промпты. Чтобы отключить её, задайте `ASKADS_TELEMETRY=0`.\n- **У Google есть поминутные квоты.** Документированные лимиты: 300 чтений и 300 записей в минуту на проект и по 60 на пользователя; пакетный вызов считается один раз, сколько бы диапазонов или запросов он ни нёс. В одной таблице не больше 10 000 000 ячеек. При `429` сервер использует задержку; чтение также повторяется после сетевых и `5xx` ошибок, а запись после неопределённой ошибки не повторяется.\n- **Постоянного опроса нет.** Сервер работает только при вызове. Если AI-приложение поддерживает задания по расписанию, оно может периодически проверять таблицу.\n\n## Техническая документация\n\n- [Каталог MCP-возможностей](./docs/capabilities/index.md) — страницы по пользовательским задачам для каждого инструмента.\n- [Все инструменты и параметры](./docs/TOOLS.md)\n- [Документация по разработке](./docs/DEVELOPMENT.md)\n- [Документация по публикации](./docs/PUBLISHING.md)\n- [Справочник Google Sheets API](https://developers.google.com/sheets/api)\n\n## Поддержка\n\nНашли ошибку или не хватает сценария? [Создайте issue](https://github.com/A1-x-Tech/mcp-google-sheets/issues) или напишите в [Telegram](https://t.me/a1_mcp).\n\n<br>\n\n<p align=\"center\">\n  <img src=\"https://github.com/ztemerbekov/a1-yandex-kit-skills/raw/main/assets/images/mona-hifive-yandex-kit-warm.gif\" alt=\"Две Моны дают пять\" width=\"256\">\n</p>\n\n<p align=\"center\">\n  Вы дочитали до конца!\n</p>\n","readmeFilename":"README.ru.md","_rev":"1-e3aa94ec9d5fd21d7472c84e698e1ab7"}