# A1 Google Merchant Center MCP [English](./README.md) | **Русский** [![npm](https://img.shields.io/npm/v/mcp-google-merchants)](https://www.npmjs.com/package/mcp-google-merchants) [![CI](https://github.com/A1-x-Tech/mcp-google-merchants/actions/workflows/ci.yml/badge.svg)](https://github.com/A1-x-Tech/mcp-google-merchants/actions/workflows/ci.yml) [![Glama](https://glama.ai/mcp/servers/A1-x-Tech/mcp-google-merchants/badges/score.svg)](https://glama.ai/mcp/servers/A1-x-Tech/mcp-google-merchants) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE) **A1 Google Merchant Center MCP** подключает AI-приложение к вашему аккаунту Google Merchant Center. Он помогает понять причины отклонения товаров, проверить фиды и промоакции, изучить отчёты и рыночные цены, а затем осознанно изменить данные товара, если это нужно. Сервер работает с данными Merchant Center для товарных объявлений: товарами, источниками данных, промоакциями и отчётами. Кампании, бюджеты и ставки относятся к Google Ads — этот сервер ими не управляет. - **22 инструмента.** 15 операций только читают данные Merchant Center; 5 меняют товары, источники данных или промоакции; 2 потенциально разрушительны. - **Ваш доступ Google.** Сервер использует ваши OAuth-данные и Merchant API v1 — отдельный аккаунт Merchant Center он не создаёт. - **Изменения с учётом источника.** Исходные данные товаров и промоакций можно менять только через API-источник. Файловый фид можно запросить повторно, но его содержимое сервер здесь не редактирует. - **Видимые границы.** Инструменты помечены как read-only, write или destructive, поэтому AI-приложение может отличить проверку от изменения рабочих данных. Начните с запроса, который только читает данные: > Какие товары отклонены и какие проблемы указывает Google для каждого из них? [Подключить сервер](#быстрый-старт) · [Посмотреть сценарии](#что-можно-поручить) · [Открыть техническую документацию](#техническая-документация) --- ## Увидеть работу за минуту > **Вы:** Какие товары отклонены и какие проблемы указывает Google для каждого из них? > > **Ассистент:** Показывает затронутые товары и объясняет проблемы на уровне товара, которые сообщает Merchant Center. > > **Вы:** Покажи текущую цену и наличие товара `SKU-123`, затем подготовь изменение наличия на `in_stock`. > > **Ассистент:** Показывает текущие исходные данные товара, API-источник, которому они принадлежат, и точное изменение. Перед обновлением данных в Merchant Center он запрашивает подтверждение. > > **Вы:** Подтверждаю изменение. > > **Ассистент:** Отправляет обновление и поясняет, что Merchant Center обрабатывает товарные данные асинхронно. Обработанный товар и его статус качества могут обновиться через несколько минут. ## Содержание - [Быстрый старт](#быстрый-старт) - [Что можно поручить](#что-можно-поручить) - [Как связаны данные Merchant Center](#как-связаны-данные-merchant-center) - [Что может измениться](#что-может-измениться) - [Как получить доступ](#как-получить-доступ) - [Конфигурация](#конфигурация) - [Данные и телеметрия](#данные-и-телеметрия) - [Ограничения и работа в фоне](#ограничения-и-работа-в-фоне) - [Техническая документация](#техническая-документация) - [Поддержка](#поддержка) ## Быстрый старт Нужны Node.js 20+, аккаунт Google Merchant Center и проект Google Cloud, зарегистрированный в Merchant Center. OAuth-данные при установке не нужны: сервер подключается прямо в диалоге, см. [«Как получить доступ»](#как-получить-доступ). 1. Добавьте сервер в AI-приложение по одной из инструкций ниже. 2. Скажите «подключи Google Merchant Center» — ассистент проведёт через создание OAuth-клиента и согласие в браузере, без конфигов и перезапуска. 3. Отправьте первый запрос, который только читает данные.
Codex
**В приложении:** 1. Откройте **Settings → MCP servers**. 2. Нажмите **Add server**. 3. Выберите **STDIO**, затем укажите команду запуска `npx -y mcp-google-merchants@latest` и четыре переменные окружения ниже. | Переменная | Значение | |---|---| | `GOOGLE_MERCHANTS_CLIENT_ID` | Ваш Google OAuth client ID | | `GOOGLE_MERCHANTS_CLIENT_SECRET` | Ваш Google OAuth client secret | | `GOOGLE_MERCHANTS_REFRESH_TOKEN` | Ваш Google OAuth refresh token | | `GOOGLE_MERCHANTS_ACCOUNT_ID` | ID аккаунта Merchant Center | 4. Нажмите **Save**, затем **Restart**. **В командной строке:** ```bash codex mcp add google-merchants \ -- npx -y mcp-google-merchants@latest ``` Проверьте подключение: ```bash codex mcp list ``` [Документация Codex MCP](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)
Claude Code
```bash claude mcp add \ --transport stdio \ --scope user \ google-merchants \ -- npx -y mcp-google-merchants@latest ``` Проверьте подключение: ```bash claude mcp list ``` [Документация Claude Code MCP](https://code.claude.com/docs/en/mcp)
Claude Desktop
Актуальный официальный путь — **Settings → Extensions**. Для пользовательского desktop extension откройте **Advanced settings → Extension Developer → Install Extension…**, выберите файл `.mcpb` и следуйте подсказкам. Этот репозиторий сейчас публикует npm-пакет со stdio и пока не содержит `.mcpb`. Поэтому используйте приведённый ниже JSON stdio-конфиг как fallback только в сборках Claude Desktop, где ещё поддерживается локальная конфигурация: ```json { "mcpServers": { "google-merchants": { "command": "npx", "args": ["-y", "mcp-google-merchants@latest"] } } } ``` В таких сборках сохраните его в `~/Library/Application Support/Claude/claude_desktop_config.json` на macOS или `%APPDATA%\Claude\claude_desktop_config.json` на Windows. [Документация Claude Desktop MCP](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop)
Cursor
Добавьте сервер уровня пользователя в `~/.cursor/mcp.json` на macOS/Linux или в `%USERPROFILE%\.cursor\mcp.json` на Windows: ```json { "mcpServers": { "google-merchants": { "type": "stdio", "command": "npx", "args": ["-y", "mcp-google-merchants@latest"] } } } ``` [Документация Cursor MCP](https://cursor.com/docs/mcp)
VS Code
Запустите **MCP: Open User Configuration** из Command Palette и добавьте: ```json { "servers": { "google-merchants": { "type": "stdio", "command": "npx", "args": ["-y", "mcp-google-merchants@latest"] } }, "inputs": [ { "type": "promptString", "id": "google_merchants_client_id", "description": "Google OAuth client ID" }, { "type": "promptString", "id": "google_merchants_client_secret", "description": "Google OAuth client secret", "password": true }, { "type": "promptString", "id": "google_merchants_refresh_token", "description": "Google OAuth refresh token", "password": true }, { "type": "promptString", "id": "google_merchants_account_id", "description": "ID аккаунта Merchant Center" } ] } ``` Проверьте сервер командой **MCP: List Servers**. [Документация VS Code MCP](https://code.visualstudio.com/docs/agent-customization/mcp-servers)
## Что можно поручить ### Найти и понять проблемы каталога - Какие товары отклонены и что Google сообщает по каждому из них? - Покажи название, цену, наличие и текущий статус товара `SKU-123`. - Какие товары отсутствуют на складе? - Покажи самые частые проблемы товаров в этом аккаунте Merchant Center. ### Изучить результаты и цены - Покажи клики и показы по товарам за июль. - Какие товары в США стоят дороже рыночного ориентира? - Какие цены рекомендует Google и какой эффект он прогнозирует? Для сравнения с рынком и рекомендаций по цене нужно бесплатное подключение Market Insights в Merchant Center. Если аккаунт не подключён, сервер объяснит, почему отчёт не возвращает строки. ### Проверить аккаунт и фиды - Покажи доступные мне аккаунты Merchant Center. - Подтверждён ли сайт? Покажи текущие настройки доставки. - Покажи источники данных товаров и промоакций и найди API-источник. - Запусти вне расписания повторное получение этого файлового фида. ### Внести осознанные изменения - Обнови цену и наличие этого товара в его API-источнике. - Создай API-источник для нового товарного фида. - Создай или обнови промоакцию, затем проверь её статус согласования. Для любого запроса, который меняет данные, сначала попросите ассистента показать целевой аккаунт, источник данных и точные поля, которые он собирается изменить. ## Как связаны данные Merchant Center Merchant Center хранит поступившие данные и итоговый статус товара раздельно: 1. В **аккаунте** находятся источники данных товаров и промоакций. 2. **Источник данных** может быть API-источником, файлом, Google Sheets, интерфейсом Merchant Center или автоматическим фидом. 3. **Исходные данные товара** — это данные, которые передал один источник. 4. **Обработанный товар** — результат обработки в Merchant Center. В нём содержатся допуски и проблемы на уровне товара. Сервер читает все перечисленные типы источников. Создавать API-источники и обновлять исходные данные товара он может только в API-источнике; записывать в файл, интерфейс или автоматический фид он не умеет. Чтобы найти товары по условию, используйте отчётный запрос: у `list_products` нет серверной фильтрации. ## Что может измениться | Операция | Что происходит | Граница подтверждения | |---|---|---| | Проверка аккаунтов, товаров, фидов, промоакций, отчётов, проблем и квот | Читает данные Merchant Center | Не меняет Merchant Center | | Создание API-источника | Добавляет источник для товарных данных или промоакций | Меняет аккаунт | | Обновление исходных данных товара | Меняет выбранные поля товара: например, цену или наличие | Меняет данные в рабочем источнике | | Добавление исходных данных товара | Полностью заменяет данные с тем же ID в этом API-источнике; при другом источнике переносит товар | Меняет данные в рабочем источнике | | Повторное получение файлового фида | Запрашивает внеплановое получение файла или Google Sheets | Запускает асинхронную работу у Google | | Создание или обновление промоакции | Создаёт или меняет промоакцию | Меняет данные в рабочем источнике | | Удаление исходных данных товара | Удаляет данные из выбранного источника | Разрушительное действие | | Технический запрос Merchant API | Может вызвать метод API без отдельного инструмента | Потенциально разрушительное действие | То, как AI-приложение запрашивает подтверждение операций записи и удаления, определяет само приложение. Сервер помечает операции как read-only, write и destructive, чтобы приложение могло показать нужную границу. ## Как получить доступ Сервер использует [Google Merchant API](https://developers.google.com/merchant/api/overview) и OAuth-скоуп `https://www.googleapis.com/auth/content`. Способов передать доступ два, и первый не требует править конфигурационные файлы. ### Подключение из диалога (рекомендуемый путь) Скажите «подключи Google Merchant Center», и ассистент пройдёт флоу вместе с вами: 1. `setup_instructions` выдаёт чек-лист: создать или выбрать проект Google Cloud, включить **Merchant API**, настроить consent screen и создать OAuth-клиент типа **Desktop app**. 2. Скачайте JSON этого клиента («Download JSON») и передайте ассистенту **путь** к файлу — `set_client` сохранит его с правами только для владельца. Секрет через переписку не проходит. 3. `start_login` возвращает ссылку на согласие Google. Откройте её **на этой же машине** и подтвердите доступ: код возвращается на одноразовый слушатель `127.0.0.1` (PKCE), а не в чат. 4. `finish_login` меняет код на токены, кладёт их в `~/.config/mcp-google-merchants/credentials.json` (права 0600) и проверяет реальным вызовом Merchant API — так незарегистрированный в Merchant Center проект ловится сразу. Токены перечитываются на каждый вызов, поэтому подключение действует немедленно — перезапускать AI-приложение не нужно. `auth_status` показывает состояние, `logout` отзывает токен и удаляет его. Регистрацию Cloud-проекта в Merchant Center это не отменяет: это шаг Merchant Center, а не OAuth. ### Переменные окружения (CI и автоматические установки) 1. Создайте или выберите **проект Google Cloud**, включите **Merchant API** и настройте OAuth consent screen. 2. В Google Cloud создайте OAuth-клиент типа **Desktop app**. Сохраните его client ID и client secret. 3. Авторизуйте Google-аккаунт, у которого есть доступ к Merchant Center, и получите refresh token для указанного scope. В этом может помочь [OAuth 2.0 Playground](https://developers.google.com/oauthplayground): включите **Use your own OAuth credentials**, укажите scope, авторизуйтесь и обменяйте код на токены. 4. Найдите ID аккаунта Merchant Center и используйте его в `GOOGLE_MERCHANTS_ACCOUNT_ID`. 5. Один раз зарегистрируйте проект Google Cloud в Merchant Center. Для этого Google требует рабочий аккаунт Merchant Center с подтверждённым сайтом и права администратора. Регистрация связывает один проект Cloud с аккаунтом Merchant Center; пока она не завершена, вызовы Merchant API из этого проекта заблокированы. Следуйте [инструкции Google по регистрации разработчика](https://developers.google.com/merchant/api/guides/quickstart/registration). Одноразовую регистрацию можно выполнить техническим инструментом `raw_request`, но при первой настройке Merchant API безопаснее следовать инструкции Google. После регистрации Google может начать принимать вызовы не сразу, а в течение пяти минут. Храните OAuth client secret и refresh token как пароли. Они находятся в конфигурации MCP-клиента и могут давать доступ к аккаунту Merchant Center. ## Конфигурация | Переменная | Обязательна | Описание | |---|---|---| | `GOOGLE_MERCHANTS_CLIENT_ID` | Нет* | OAuth 2.0 client ID. | | `GOOGLE_MERCHANTS_CLIENT_SECRET` | Нет* | OAuth 2.0 client secret. | | `GOOGLE_MERCHANTS_REFRESH_TOKEN` | Нет* | OAuth refresh token с доступом Merchant API. | | `GOOGLE_MERCHANTS_ACCESS_TOKEN` | Нет* | Короткоживущая альтернатива трём OAuth-переменным выше. | | `GOOGLE_MERCHANTS_ACCOUNT_ID` | Нет | ID аккаунта Merchant Center по умолчанию. В конкретном запросе можно выбрать другой доступный аккаунт. | | `GOOGLE_MERCHANTS_OAUTH_PORT` | Нет | Фиксированный порт loopback-слушателя для входа из диалога; нужен при пробросе портов по SSH. | | `GOOGLE_MERCHANTS_API_BASE` | Нет | Переопределяет базовый URL Merchant API. | | `GOOGLE_MERCHANTS_TOKEN_URL` | Нет | Переопределяет OAuth token endpoint. | | `GOOGLE_MERCHANTS_TIMEOUT_MS` | Нет | Тайм-аут одного запроса в миллисекундах; по умолчанию `60000`. | | `GOOGLE_MERCHANTS_MAX_RETRIES` | Нет | Максимальное число повторов при временных ошибках; по умолчанию `3`. | \* Используйте либо client ID, client secret и refresh token вместе, либо заранее полученный access token. Access token обычно истекает примерно через час; refresh token позволяет серверу получать новый access token при необходимости. ## Данные и телеметрия Сервер запускается локально как процесс из AI-приложения. Он отправляет запросы Merchant Center в Google и обновляет OAuth access tokens через OAuth endpoint Google. Сервер отправляет анонимную телеметрию, чтобы считать активные установки и востребованность инструментов: случайный ID установки, версию пакета, версию AI-клиента, версии Node.js и операционной системы, а также имя инструмента. OAuth-токены, данные Merchant Center, аргументы инструментов и промпты он не отправляет и не хранит. При вызове инструмента сервер также отправляет его исход, а при ошибке - фрагмент её текста: код и сообщение, в которых e-mail, адреса, токены, числа от 4 цифр и текст в кавычках заменены на «#». Если в тексте ошибки есть значение из запроса, оно тоже может попасть во фрагмент. Отключить телеметрию для MCP-серверов A1 можно так: ```bash ASKADS_TELEMETRY=0 ``` ## Ограничения и работа в фоне - **Merchant Center обрабатывает данные асинхронно.** Новый, изменённый или удалённый исходный товар может появиться среди обработанных товаров через несколько минут. Проблемы согласования товаров и промоакций возникают позже, а не как мгновенная ошибка API. - **Market Insights подключается отдельно.** Отчёты о конкурентности цены и рекомендуемых ценах возвращают данные только после бесплатного подключения программы Market Insights. - **Квоты зависят от аккаунта и метода API.** Текущее потребление показывает `list_method_quotas`; суточные счётчики Google сбрасываются в 12:00 UTC. - **Временные лимиты обрабатываются осторожно.** При ответе Google `429` сервер учитывает `Retry-After`, если он передан, и делает ограниченное число повторов. После неопределённой сетевой или серверной ошибки он не повторяет запись. - **Постоянного наблюдения нет.** Сервер работает только во время вызова из AI-приложения. Если приложение поддерживает задания по расписанию, ему можно поручить периодически проверять проблемы товаров или расход квоты. - **У агрегированных проблем товаров есть ограничение по типу аккаунта.** `list_product_issues` работает для обычных аккаунтов и субаккаунтов, но не для родительских advanced-аккаунтов. ## Техническая документация - [Каталог MCP-возможностей](./docs/capabilities/index.md) — страницы по пользовательским задачам для каждого инструмента. - [Все инструменты и их параметры](./docs/TOOLS.md) - [Документация по разработке](./docs/DEVELOPMENT.md) - [Документация по публикации](./docs/PUBLISHING.md) - [Обзор Google Merchant API](https://developers.google.com/merchant/api/overview) - [Аутентификация Google Merchant API](https://developers.google.com/merchant/api/guides/quickstart/authentication) - [Регистрация разработчика в Google](https://developers.google.com/merchant/api/guides/quickstart/registration) ## Поддержка Нашли ошибку или не хватает сценария? [Создайте issue](https://github.com/A1-x-Tech/mcp-google-merchants/issues) или напишите в [Telegram](https://t.me/a1_mcp).

Две Моны дают пять

Вы дочитали до конца!