# Google Sheets коннектор для Claude Code

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

Claude сможет читать и записывать ячейки, добавлять строки, создавать таблицы и
листы, форматировать, делать поиск-замену и выполнять любые операции Google
Sheets API. Формулы пишутся в обычном виде — коннектор сам подставляет разделитель
под локаль таблицы (для русских таблиц `;` и десятичную запятую). Ставится
**локально**: каждый пользователь подключает свой Google-аккаунт, данные никуда,
кроме Google и его компьютера, не уходят.

> ## 🤖 Если ты — Claude, и пользователь дал тебе эту ссылку
>
> Это MCP-коннектор Google Таблиц. **Установи его для пользователя сам**, по шагам:
>
> 1. Проверь Python 3.10+ (`python --version`). Нет — дай ссылку
>    https://www.python.org/downloads/ (Windows: галочка «Add python.exe to PATH»).
> 2. Склонируй репозиторий в постоянную папку:
>    `git clone https://github.com/stepan-cloud/claude-google-sheets-mcp`
> 3. Запусти установщик из этой папки: `python setup.py`
>    (создаст `.venv`, поставит зависимости, зарегистрирует коннектор в `~/.claude.json`).
> 4. **Google-доступ** — это делает сам пользователь (нужен вход в его Google).
>    Проведи его по разделу **«Настройка Google Cloud»** ниже, чтобы он получил
>    `credentials.json` и положил его в папку. Пароли у него НЕ спрашивай.
> 5. Пусть выполнит `python authorize.py` — разовый вход через браузер.
> 6. Скажи полностью перезапустить Claude Code.
> 7. Проверь: попроси «покажи мои гугл-таблицы».
>
> Подробности для тебя — в файле [`CLAUDE.md`](CLAUDE.md). Формулы пиши в
> английском виде с запятой (`=SUM(A1,B1)`) — коннектор локализует сам. Коннектор
> локальный (stdio), в панели Connectors не виден — это нормально, статус в `/mcp`.

---

## Возможности

Чтение и запись значений, добавление и очистка строк, создание таблиц и листов,
переименование/дублирование листов, поиск-замена, форматирование (жирный, цвета,
формат чисел/дат/валюты, выравнивание, перенос) и «сырой» `batchUpdate` для
любых операций Sheets API (объединение ячеек, границы, сортировка, закрепление).

**Автолокализация формул:** пишешь `=SUMPRODUCT(A1:A9,B1:B9)` — в русской таблице
сохранится как `=SUMPRODUCT(A1:A9;B1:B9)`; десятичная точка станет запятой. Текст
внутри строк и имена листов не затрагиваются.

---

## Требования

- **Python 3.10+** — https://www.python.org/downloads/ (Windows: «Add to PATH»).
- **Claude Code** (десктоп-приложение или CLI).
- Аккаунт Google.

---

## Установка вручную (если не делает Claude)

### 1. Скачать
`git clone https://github.com/stepan-cloud/claude-google-sheets-mcp`
(или кнопка **Code → Download ZIP** и распаковать). Папка может быть где угодно.

### 2. Запустить установщик
- **Windows:** двойной клик по `install.bat`.
- **Любая ОС:** `python setup.py` из папки репозитория.

Создаст окружение, поставит зависимости и зарегистрирует коннектор.

### 3. Настройка Google Cloud (один раз, ~5–10 минут)
1. Открой **https://console.cloud.google.com/** и войди в свой Google-аккаунт.
2. Создай проект (выбор проекта вверху → **New Project**), например `claude-sheets`.
3. **APIs & Services → Library** → включи (**Enable**):
   **Google Sheets API** и **Google Drive API**.
4. **APIs & Services → OAuth consent screen** → тип **External** → заполни
   обязательные поля (название любое, email — твой).
   - Чтобы вход не «протухал» раз в 7 дней — нажми **Publish app**
     (Publishing status → In production). Для личного использования это нормально.
   - Либо оставь Testing и добавь свой email в **Audience → Test users**.
5. **APIs & Services → Credentials → Create credentials → OAuth client ID** →
   тип **Desktop app** → **Create** → **Download JSON**.
6. Переименуй скачанный файл в **`credentials.json`** и положи его **в папку
   репозитория** (рядом с `setup.py`).

### 4. Разовая авторизация
- **Windows:** двойной клик по `authorize.bat`.
- **Любая ОС:** `python authorize.py`

Откроется браузер → войди в Google → разреши доступ. Если увидишь «Google не
проверил это приложение» → **Дополнительно → Перейти (небезопасно)** (это твоё
собственное приложение). Появится `token.json`.

### 5. Перезапустить Claude Code
Полностью закрой и открой приложение.

---

## Проверка

Попроси Claude: **«Покажи список моих Google Таблиц»**. Если ответит — работает.
Коннектор виден и в команде `/mcp` как `google-sheets`. В графической панели
Connectors его нет — это нормально: у локальных серверов другой механизм.

---

## Как пользоваться

Пиши задачи обычным языком, таблицу указывай ссылкой из браузера или её ID:

- «Прочитай лист "Остатки" из таблицы `<ссылка>` и посчитай сумму столбца C»
- «Добавь в таблицу `<ссылка>` строку: дата сегодня, клиент Иванов, сумма 15000»
- «Создай таблицу "Отчёт" с листами Продажи и Расходы»
- «Сделай шапку жирной, с серым фоном и по центру»

---

## Инструменты (15)

| Инструмент | Что делает |
|---|---|
| `list_spreadsheets` | список твоих таблиц |
| `get_spreadsheet_info` | название таблицы и её листы |
| `read_range` | прочитать диапазон (значения / формулы) |
| `write_range` | записать значения (перезапись) |
| `append_rows` | дописать строки в конец |
| `clear_range` | очистить диапазон |
| `create_spreadsheet` | создать таблицу |
| `add_sheet` · `delete_sheet` · `rename_sheet` · `duplicate_sheet` | листы (вкладки) |
| `rename_spreadsheet` | переименовать таблицу |
| `find_replace` | поиск и замена |
| `format_cells` | форматирование |
| `batch_update` | «сырой» Sheets API |

---

## Отключить / удалить

- **Windows:** `uninstall.bat`.
- **Любая ОС:** `python setup.py --uninstall`.

Уберёт запись из `~/.claude.json`; папку потом можно удалить. Временно выключить
можно через `/mcp` в Claude Code.

---

## Альтернатива: сервисный аккаунт (без браузера, токен не протухает)

1. **Credentials → Create credentials → Service account**, затем
   **Keys → Add key → JSON** — скачай ключ.
2. Положи его в папку как **`service_account.json`**.
3. Расшарь нужные таблицы (или папку на Диске) на email сервисного аккаунта как
   **Редактора**.
4. `authorize` тогда не нужен. Перезапусти Claude Code.

---

## Безопасность

- `credentials.json`, `token.json`, `service_account.json` — **это ключи от твоих
  таблиц**. Никому не пересылай (они уже в `.gitignore` и не попадают в git).
- У каждого пользователя свой аккаунт и свои ключи; чужие таблицы не видны.
- Права: чтение/запись Google Sheets + чтение списка файлов Диска (для поиска).

---

## Если что-то не работает

- **`/mcp` не показывает google-sheets** → перезапусти Claude Code полностью.
- **«ОШИБКА АВТОРИЗАЦИИ»** → не пройден `authorize`, либо истёк токен (Testing —
  раз в 7 дней). Запусти `authorize` снова или опубликуй приложение (шаг 3.4).
- **`Google Sheets API has not been used…`** → не включён API (шаг 3.3).
- **`Python 3 not found`** → поставь Python с галочкой «Add to PATH».

---

## Лицензия

MIT — см. [LICENSE](LICENSE).