gbp-mcp

Автономный MCP-сервер для Google Business Profile. Он предоставляет аккаунты, местоположения, отзывы, публикации, медиа, вопросы и ответы, аналитику и несколько действий записи в виде JSON-инструментов для Cursor, Claude Desktop и Claude Code.

Этот репозиторий не является приложением Streamlit GMB-Management-System. Здесь нет веб-интерфейса, экспорта в PDF, графиков Plotly, панели i18n или составления ответов Gemini. Вызовы Google API находятся в этом репозитории (data_fetcher.py, drive_helper.py). Вам не нужно клонировать или запускать проект Streamlit.

Инструменты

Чтение:

• list_accounts

• list_locations

• get_daily_metrics

• get_search_keywords

• list_reviews

• list_posts

• list_media

• list_questions

• profile_health_check

Запись:

• create_local_post

• upload_image_to_drive

• reply_to_review

Помощники аутентификации:

• start_oauth

• complete_oauth

Каждый инструмент возвращает только JSON (без DataFrame, PDF или объектов графиков).

Идентификаторы местоположений принимают accounts/{accountId}/locations/{locationId}, locations/{locationId} или просто id. Вызовы v4 (отзывы, публикации, медиа) проходят через resolve_location_parent. Даты в формате YYYY-MM-DD. Загрузки на Drive принимают base64-байты изображения (file_base64) и могут возвращать публичный URL для публикаций GBP.

Related MCP server: google-ads-mcp

Требования

• Python 3.10+

• Клиент OAuth пользователя Google Cloud (Desktop или Web). Сервисные аккаунты не поддерживаются.

• Эти области OAuth:

  • https://www.googleapis.com/auth/business.manage

  • https://www.googleapis.com/auth/drive.file

  • https://www.googleapis.com/auth/drive.metadata.readonly

Включите Google API, которые будут вызывать ваши инструменты, обычно:

• My Business Account Management API

• My Business Business Information API

• My Business Q&A API

• Business Profile Performance API

• Google Drive API

• Google My Business API (v4 discovery, используется для отзывов / публикаций / медиа)

Установка

git clone https://github.com/marcusbtc/gbp-mcp.git
cd gbp-mcp
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt

Скопируйте .env.example и экспортируйте значения, или поместите их в блок env вашего MCP-клиента. Не коммитьте .env, client_secret.json или файлы токенов.

cp .env.example .env

Аутентификация (только пользовательский OAuth)

Никогда не помещайте токены, токены обновления или client_secret.json в git.

Вам нужны идентификатор и секрет клиента OAuth Google Cloud (GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET). Опционально: поместите локальный client_secret.json в корень репозитория (игнорируется git).

Добавьте этот URI перенаправления в клиенте OAuth (если вы его не переопределяете):

http://localhost:8753/

Затем выберите один из вариантов:

1. Токен на вызов — передавайте access_token в любом инструменте.

2. Токен окружения — установите GOOGLE_ACCESS_TOKEN. Опциональное обновление: GOOGLE_REFRESH_TOKEN плюс идентификатор/секрет клиента.

3. Локальный помощник (открывает браузер, записывает игнорируемый git файл токена, по умолчанию .gmb-mcp-token.json):

python mcp_server.py --oauth

4. Инструменты MCP — вызовите start_oauth, подтвердите доступ, затем complete_oauth с параметром запроса code из URL перенаправления.

complete_oauth и --oauth никогда не выводят токены. Переопределите путь к токену с помощью GMB_MCP_TOKEN_PATH. Переопределите перенаправление с помощью GOOGLE_REDIRECT_URI.

Запуск

stdio (по умолчанию — Cursor, Claude Desktop, Claude Code):

python mcp_server.py
# or: python -m src.gmb_mcp

Опциональный Streamable HTTP:

python mcp_server.py --http --host 127.0.0.1 --port 8765

Endpoint: http://127.0.0.1:8765/mcp

Подключение из Cursor

Добавьте в настройки MCP (проект .cursor/mcp.json или пользовательская конфигурация MCP). Используйте абсолютный путь. Не помещайте токены в коммитимый файл.

{
  "mcpServers": {
    "google-business-profile": {
      "command": "python",
      "args": ["mcp_server.py"],
      "cwd": "/absolute/path/to/gbp-mcp",
      "env": {
        "GOOGLE_CLIENT_ID": "<your-oauth-client-id>",
        "GOOGLE_CLIENT_SECRET": "<your-oauth-client-secret>"
      }
    }
  }
}

Если у вас уже есть токен доступа пользователя и вы предпочитаете не запускать --oauth:

{
  "mcpServers": {
    "google-business-profile": {
      "command": "python",
      "args": ["mcp_server.py"],
      "cwd": "/absolute/path/to/gbp-mcp",
      "env": {
        "GOOGLE_ACCESS_TOKEN": "<your-oauth-access-token>"
      }
    }
  }
}

Укажите command на интерпретатор venv, если не хотите сначала активировать его, например /absolute/path/to/gbp-mcp/.venv/bin/python.

HTTP вместо stdio (сначала запустите сервер самостоятельно):

{
  "mcpServers": {
    "google-business-profile": {
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

Подключение из Claude Desktop / Claude Code

Claude Desktop (claude_desktop_config.json) и Claude Code используют ту же форму stdio:

{
  "mcpServers": {
    "google-business-profile": {
      "command": "/absolute/path/to/gbp-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/gbp-mcp/mcp_server.py"],
      "env": {
        "GOOGLE_CLIENT_ID": "<your-oauth-client-id>",
        "GOOGLE_CLIENT_SECRET": "<your-oauth-client-secret>"
      }
    }
  }
}

Запустите python mcp_server.py --oauth один раз в этой рабочей директории, чтобы создать .gmb-mcp-token.json, или установите GOOGLE_ACCESS_TOKEN.

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

• Никогда не коммитьте client_secret.json, .env или .gmb-mcp-token.json.

• Никогда не вставляйте токены доступа в чат, issues или скриншоты.

• Инструменты и помощники OAuth не возвращают токены.

• Загрузки на Drive с make_public=true создают общедоступный URL файла. Используйте это только когда намерены прикрепить изображение к публичной публикации GBP.

Разработка

pip install -r requirements-dev.txt
ruff check src tests mcp_server.py
pytest
python -m py_compile mcp_server.py data_fetcher.py drive_helper.py health_check.py
python mcp_server.py --help

Лицензия

MIT (см. LICENSE).