# Архитектура Google Sheets MCP сервера
## 🏗️ Общая схема
```
┌─────────────────────────────────────────────────────────────┐
│ ТВОЙ КОМПЬЮТЕР │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Claude Code (CLI) │ │
│ │ ┌────────────────────────────────────────────────┐ │ │
│ │ │ Ты пишешь команду: │ │ │
│ │ │ "Прочитай данные из моей таблицы A1:D10" │ │ │
│ │ └────────────────────────────────────────────────┘ │ │
│ │ ↓ │ │
│ │ ┌────────────────────────────────────────────────┐ │ │
│ │ │ Claude AI видит инструмент: │ │ │
│ │ │ read_sheet(spreadsheet_id, range) │ │ │
│ │ └────────────────────────────────────────────────┘ │ │
│ │ ↓ │ │
│ │ ┌────────────────────────────────────────────────┐ │ │
│ │ │ MCP Server (Node.js) │ │ │
│ │ │ ├── read_sheet │ │ │
│ │ │ ├── write_sheet │ │ │
│ │ │ ├── append_sheet │ │ │
│ │ │ ├── get_metadata │ │ │
│ │ │ └── clear_sheet │ │ │
│ │ └────────────────────────────────────────────────┘ │ │
│ │ ↓ │ │
│ │ ┌────────────────────────────────────────────────┐ │ │
│ │ │ Google Sheets API Client │ │ │
│ │ │ (googleapis npm пакет) │ │ │
│ │ └────────────────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────────┘ │
│ ↓ │
│ ИНТЕРНЕТ (безопасное соединение HTTPS) │
│ ↓ │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ GOOGLE CLOUD (облако Google) │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Google Sheets API │ │
│ │ (Получает запросы и управляет таблицами) │ │
│ └──────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Твои Google Sheets таблицы │ │
│ │ ┌──────────────────────────────────────────────┐ │ │
│ │ │ "Sales Data" | "Logs" | "Results" │ │ │
│ │ │ ┌──────────┐ ┌──────┐ ┌────────────────┐ │ │ │
│ │ │ │ Row 1 │ │ │ │ Analysis Date │ │ │ │
│ │ │ │ Row 2 │ │ Log │ │ Result Value │ │ │ │
│ │ │ │ ... │ │ Log │ │ Status │ │ │ │
│ │ │ └──────────┘ │ │ └────────────────┘ │ │ │
│ │ │ └──────┘ │ │ │
│ │ └──────────────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
```
---
## 🔄 Поток данных: Чтение
```
Пользователь в Claude:
"Прочитай данные из таблицы A1:D10"
↓
├─→ Claude распознает инструмент
├─→ Claude вызывает: read_sheet({
│ spreadsheet_id: "1A2B3C...",
│ range: "A1:D10"
│ })
↓
MCP Server получает запрос
↓
├─→ Проверяет параметры
├─→ Создает Google Sheets API запрос
├─→ Отправляет HTTPS запрос в Google
↓
Google Sheets API обрабатывает
↓
├─→ Проверяет права доступа (credentials.json)
├─→ Находит таблицу по ID
├─→ Извлекает данные из диапазона A1:D10
├─→ Возвращает JSON ответ
↓
MCP Server получает ответ
↓
├─→ Формирует результат
├─→ Возвращает в Claude
↓
Claude получает данные
↓
├─→ Анализирует
├─→ Показывает результат пользователю
↓
✓ Готово!
```
---
## 🔄 Поток данных: Запись
```
Пользователь в Claude:
"Напиши результаты в ячейки A1:D1"
↓
Claude вызывает: write_sheet({
spreadsheet_id: "1A2B3C...",
range: "A1:D1",
values: [["Name", "Age", "City", "Status"]]
})
↓
MCP Server получает запрос
↓
├─→ Проверяет параметры
├─→ Форматирует данные
├─→ Создает Google Sheets API запрос
├─→ Отправляет HTTPS запрос
↓
Google Sheets API
↓
├─→ Проверяет права (credentials.json)
├─→ Обновляет ячейки
├─→ Возвращает подтверждение
↓
MCP Server
↓
├─→ Возвращает результат в Claude
↓
Claude
├─→ Подтверждает успех
├─→ Показывает пользователю что данные записаны
↓
✓ Таблица обновлена!
```
---
## 🔐 Аутентификация и безопасность
```
┌─────────────────────────────────────────────┐
│ Твоя система │
│ │
│ credentials.json │
│ { │
│ "type": "service_account", │
│ "project_id": "google-sheets-mcp", │
│ "private_key": "-----BEGIN PRIVATE...", │
│ "client_email": "google-sheets-mcp@...", │
│ ... │
│ } │
│ ↓ │
│ MCP Server (index.js) │
│ ├─ Загружает credentials.json │
│ ├─ Создает GoogleAuth │
│ ├─ Получает JWT токен │
│ ↓ │
└─────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ Google Cloud │
│ │
│ ├─ Проверяет JWT токен │
│ ├─ Проверяет что это service_account │
│ ├─ Проверяет права доступа (Editor) │
│ ├─ Выполняет операцию │
│ ├─ Возвращает результат │
│ │
└─────────────────────────────────────────────┘
```
**Как это работает:**
1. **Service Account** - специальный аккаунт без пароля
2. **Приватный ключ** (в credentials.json) - используется для подписания запросов
3. **Google API** - проверяет подпись и дает доступ
4. **Шифрование HTTPS** - все данные передаются зашифрованно
**Безопасность:**
- ✅ Приватный ключ никогда не передается
- ✅ Каждый запрос подписывается
- ✅ Google проверяет подпись
- ✅ Только авторизованные таблицы доступны
---
## 📁 Структура файлов
```
google-sheets-mcp/
│
├── index.js
│ ├── initializeGoogleAuth()
│ │ ├─ Загружает credentials.json
│ │ ├─ Создает Google Auth клиент
│ │ └─ Инициализирует Sheets API
│ │
│ ├── readGoogleSheet(spreadsheetId, range)
│ │ ├─ API: sheets.spreadsheets.values.get()
│ │ └─ Возвращает: {data, range, rowCount, columnCount}
│ │
│ ├── writeGoogleSheet(spreadsheetId, range, values)
│ │ ├─ API: sheets.spreadsheets.values.update()
│ │ └─ Возвращает: {updatedRows, updatedColumns, updatedCells}
│ │
│ ├── appendGoogleSheet(spreadsheetId, range, values)
│ │ ├─ API: sheets.spreadsheets.values.append()
│ │ └─ Возвращает: {updatedRows, updatedColumns, updatedCells}
│ │
│ ├── getSpreadsheetMetadata(spreadsheetId)
│ │ ├─ API: sheets.spreadsheets.get()
│ │ └─ Возвращает: {sheets: [{title, sheetId, gridProperties}]}
│ │
│ ├── clearGoogleSheetCells(spreadsheetId, range)
│ │ ├─ API: sheets.spreadsheets.values.clear()
│ │ └─ Возвращает: {clearedRange}
│ │
│ └── MCP Server Setup
│ ├─ Регистрирует 5 инструментов
│ ├─ Обрабатывает запросы Claude
│ └─ Возвращает результаты через stdio
│
├── package.json
│ └─ Зависимости:
│ ├─ @modelcontextprotocol/sdk (MCP)
│ ├─ googleapis (Google API)
│ ├─ google-auth-library (OAuth2)
│ └─ dotenv (.env файлы)
│
├── credentials.json (⬅️ ТЫ ДОЛЖЕН СКАЧАТЬ)
│ └─ JSON ключ от Service Account
│
└── Документация
├─ START_HERE.md
├─ QUICK_START.md
├─ GOOGLE_CLOUD_SETUP.md
├─ CHECKLIST.md
├─ README.md
├─ EXAMPLES.md
├─ ARCHITECTURE.md (этот файл)
├─ SETUP.md
└─ .env.example
```
---
## 🔗 Соединения и зависимости
```
┌──────────────────────────────────────────────────┐
│ Claude Code CLI │
│ (claude-haiku-4-5-20251001) │
└──────────────────────────────────────────────────┘
↑
│ stdio (стандартный ввод-вывод)
│
┌──────────────────────────────────────────────────┐
│ MCP Server (Node.js) │
│ │
│ node index.js │
│ ├─ @modelcontextprotocol/sdk │
│ │ └─ Обработка MCP протокола │
│ │ │
│ ├─ googleapis │
│ │ └─ Клиент для Google Sheets API │
│ │ │
│ ├─ google-auth-library │
│ │ └─ OAuth2 аутентификация │
│ │ │
│ └─ dotenv │
│ └─ Загрузка переменных окружения │
└──────────────────────────────────────────────────┘
↑
│ HTTPS/REST API
│
┌──────────────────────────────────────────────────┐
│ Google Sheets API (v4) │
│ sheets.googleapis.com/v4/... │
└──────────────────────────────────────────────────┘
↑
│ Управление данными
│
┌──────────────────────────────────────────────────┐
│ Твои Google Sheets таблицы │
│ │
│ 📊 "Sales Data" │
│ 📊 "Logs" │
│ 📊 "Results" │
│ 📊 ... │
└──────────────────────────────────────────────────┘
```
---
## ⏱️ Тайминги и производительность
```
Операция чтения (read_sheet):
┌────────────────────────────────┐
│ Всего времени: ~500ms │
├────────────────────────────────┤
│ 1. Подписание запроса 50ms │
│ 2. HTTP запрос 150ms │
│ 3. Обработка Google 200ms │
│ 4. Получение ответа 50ms │
│ 5. Форматирование 50ms │
└────────────────────────────────┘
Операция записи (write_sheet):
┌────────────────────────────────┐
│ Всего времени: ~600ms │
├────────────────────────────────┤
│ 1. Подписание запроса 50ms │
│ 2. HTTP запрос 200ms │
│ 3. Обновление Google 300ms │
│ 4. Получение ответа 50ms │
└────────────────────────────────┘
Лимиты Google API:
├─ 300 requests/minute для большинства операций
├─ 1,000 requests/minute для read операций
├─ 500 requests/minute для write операций
└─ По 10 million cells per spreadsheet максимум
```
---
## 🐛 Обработка ошибок
```
MCP Server обрабатывает:
┌─────────────────────────────────┐
│ Ошибка при подписании │
│ ├─ Причина: Неверный ключ │
│ └─ Решение: Перезагрузить │
└─────────────────────────────────┘
┌─────────────────────────────────┐
│ Ошибка при подключении │
│ ├─ Причина: Интернет │
│ └─ Решение: Повторить запрос │
└─────────────────────────────────┘
┌─────────────────────────────────┐
│ Ошибка доступа (403) │
│ ├─ Причина: Нет прав │
│ └─ Решение: Дать доступ │
└─────────────────────────────────┘
┌─────────────────────────────────┐
│ Ошибка не найдена (404) │
│ ├─ Причина: Неверный ID │
│ └─ Решение: Проверить ID │
└─────────────────────────────────┘
Все ошибки передаются Claude в формате:
{
"success": false,
"error": "Описание ошибки"
}
```
---
## 🚀 Масштабируемость
```
Сервер может обрабатывать:
├─ Одновременно: 1 запрос (stdio)
├─ Последовательно: Неограниченно
├─ Размер данных: До 10 million cells
├─ Скорость: ~500ms на операцию
└─ Rate limit: 300 requests/minute
Если нужна большая производительность:
├─ Используй несколько MCP сервер инстансов
├─ Кэшируй результаты читаемых операций
├─ Батчируй записи (write сразу много строк)
└─ Используй более быструю модель Claude
```
---
## 📊 Диаграмма классов и функций
```
index.js
│
├── GoogleAuth
│ ├── credentials.json
│ ├── Google Auth Client
│ └── Sheets API Client
│
├── Functions
│ ├── initializeGoogleAuth()
│ ├── readGoogleSheet(id, range) → {data, range, rowCount}
│ ├── writeGoogleSheet(id, range, values) → {updated...}
│ ├── appendGoogleSheet(id, range, values) → {updated...}
│ ├── getSpreadsheetMetadata(id) → {sheets: [...]}
│ └── clearGoogleSheetCells(id, range) → {clearedRange}
│
└── MCP Server
├── ListToolsRequestSchema Handler
│ └── Возвращает 5 инструментов
│
└── CallToolRequestSchema Handler
├── Маршрутизирует на правильную функцию
├── Обрабатывает параметры
├── Вызывает Google API
└── Возвращает результат
```
---
Теперь ты понимаешь как всё работает! 🎯
Вопросы? Спроси! 💬
