# Google Sheets MCP Server для Claude Code

Этот MCP сервер позволяет Claude читать и писать данные в твои Google Sheets напрямую, без необходимости выгружать таблицы вручную.

## Что это дает для GAS разработки?

- 📊 **Claude видит результаты скрипта** — читает данные из таблиц в реальном времени
- ✅ **Быстрая отладка** — не нужно выгружать таблицу каждый раз
- 🚀 **Автоматизация** — Claude может писать результаты обратно в таблицу
- 📈 **Мониторинг** — читай логи выполнения скриптов прямо из Claude

## Функциональность

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

1. **read_sheet** - чтение данных из диапазона
   ```
   Прочитай данные из таблицы A1:D10 в моей таблице
   ```

2. **write_sheet** - запись данных в диапазон
   ```
   Напиши результаты в ячейки A1:C5 моей таблицы
   ```

3. **append_sheet** - добавление данных в конец
   ```
   Добавь новую строку в конец таблицы
   ```

4. **get_metadata** - получение информации о таблице
   ```
   Какие листы есть в моей таблице?
   ```

5. **clear_sheet** - очистка диапазона
   ```
   Очисти ячейки A1:D10
   ```

## Быстрая установка

### 1. Подготовка Google Cloud

Смотри подробно в файле `SETUP.md`:

```bash
# В общих словах:
1. Создай проект в Google Cloud Console
2. Включи Google Sheets API
3. Создай Service Account
4. Скачай JSON ключ → переименуй в credentials.json
5. Положи credentials.json в папку проекта
6. Дай доступ к твоим таблицам сервис-аккаунту
```

### 2. Регистрация в Claude Code

После создания `credentials.json`:

```bash
cd D:\google-sheets-mcp

# Зарегистрируй сервер
claude mcp add --transport stdio google-sheets-mcp --env GOOGLE_CREDENTIALS_PATH="D:/google-sheets-mcp/credentials.json" -- node "D:/google-sheets-mcp/index.js"
```

### 3. Готово!

Теперь используй в Claude:

```
Прочитай данные из моей Google Sheets таблицы (ID: 1A2B3C4D5E...) диапазон A1:D10
```

## Структура проекта

```
google-sheets-mcp/
├── index.js              # Главный файл MCP сервера
├── package.json          # Зависимости Node.js
├── credentials.json      # Google API ключ (скачать!)
├── .env.example          # Пример переменных окружения
├── SETUP.md              # Подробное руководство установки
├── README.md             # Этот файл
└── node_modules/         # Зависимости (создается при npm install)
```

## Как получить ID таблицы?

1. Открой свою Google Sheets таблицу
2. Посмотри URL:
   ```
   https://docs.google.com/spreadsheets/d/1A2B3C4D5E6F7G8H9I0J/edit
                                        ^^^^^^^^^^^^^^^^^^^
                                        Это ID таблицы
   ```

## Примеры использования в Claude

### Чтение данных
```
Прочитай данные с листа "Results" диапазон A1:C20 из таблицы 1A2B3C4D...
```

### Запись результатов
```
Напиши следующие данные в мою таблицу:
- Лист: "Logs"
- Диапазон: A1
- Значения: [["Date", "Result"], ["2025-01-15", "Success"], ["2025-01-16", "Error"]]
```

### Добавление логов
```
Добавь в конец листа "Logs" новую строку с датой и результатом выполнения
```

## Решение проблем

### "Credentials file not found"
- Проверь что `credentials.json` находится в папке `D:\google-sheets-mcp\`
- Убедись что путь в переменной `GOOGLE_CREDENTIALS_PATH` правильный

### "Permission denied"
- Убедись что дал права доступа сервис-аккаунту на таблицу
- Проверь что это service account email, а не твой личный

### Сервер не стартует
- Проверь что установлены зависимости: `npm install`
- Убедись что Node.js установлен: `node --version`

## Технические детали

- **Язык**: Node.js (JavaScript)
- **MCP SDK версия**: 1.20.1+
- **Google API**: Sheets API v4
- **Аутентификация**: Service Account (OAuth2)
- **Транспорт**: stdio (стандартный ввод-вывод)

## Лимиты и ограничения

- Google API имеет rate limit (300 requests в минуту для читаемых операций)
- Максимальный размер одной ячейки: 50,000 символов
- Максимум 10,000,000 ячеек в одной таблице

## Дальнейшее развитие

Можно расширить сервер на:
- Работу с Google Docs
- Работу с Google Forms
- Создание новых таблиц
- Форматирование ячеек (цвета, шрифты)
- Создание чартов и графиков

## Вопросы?

Если что-то не работает:
1. Прочитай `SETUP.md` еще раз
2. Проверь логи ошибок в консоли
3. Убедись что credentials.json валидный JSON

---

**Авторство**: Создано для использования с Claude Code и Google Apps Script проектами