place-ratings-analyzer

日本語版: README_ja.md

MCP-сервер, который получает и анализирует оценки отзывов Google Maps — не только средний звёздный рейтинг, но и полную разбивку по количеству оценок от ★1 до ★5. Используйте его вместе с ИИ-приложением, таким как Claude Desktop.

Для чего нужен этот инструмент?

ИИ-приложения, такие как Claude Desktop, уже могут показать вам репутацию ресторана в виде числа — «средний рейтинг ★4.0». Но одно это число не может сказать, группируются ли оценки вокруг ★4 или разделяются между ★5 и ★1. Этот сервер ищет отзывы о месте в Google Maps, получает фактическую разбивку по звёздам, а затем даёт оценку на основе этой картины. Подключите этот сервер к своему ИИ-приложению, и оно сможет исследовать глубже за вас — проверять репутацию конкретного места или находить места, где оценки разделились.

Related MCP server: Local Business Data MCP Server

Установка

Установка этого сервера требует определённых навыков работы с компьютером. Если что-то ниже непонятно, попробуйте показать этот файл ИИ-приложению и задать ему вопросы, или рассмотрите возможность использования агентной функции, такой как Cowork, чтобы поручить установку ему.

Требования

• Этот сервер работает на Docker.

  • На Windows для Docker требуется WSL. Если он у вас ещё не установлен, откройте PowerShell (или аналогичный терминал) от имени администратора и выполните:

    • wsl --install

  • Это установит WSL и всё остальное необходимое одним шагом. После завершения перезапустите Windows.

  • После перезапуска откройте «Ubuntu» из меню «Пуск». При первом запуске вас попросят создать имя пользователя и пароль Linux — выберите любые.

• Есть два способа установить сам Docker:

  1. Установите Docker Desktop.

     • Это более простой путь.

     • Если вы используете его в коммерческих целях (например, в компании), проверьте условия лицензии — в некоторых ситуациях требуется платный план.

  2. Установите его из командной строки в Ubuntu или другой среде Linux.

     • В отличие от Docker Desktop, это бесплатно и для коммерческого использования. Выполните:

     • sudo apt install -y docker.io

     • В зависимости от вашего окружения может потребоваться дополнительная настройка помимо этой команды (например, добавление собственного apt-репозитория Docker). Подробности смотрите в интернете или в документации Docker.

Загрузка репозитория

• Загрузите его либо с помощью git clone, либо в виде ZIP-файла со страницы этого репозитория.

• Чтобы правильно клонировать все файлы в Windows, включите режим разработчика Windows и добавьте эту опцию к git clone:

  • -c core.symlinks=true

  • Без неё некоторые функции для разработчиков (Agent Skills) будут ограничены — сам сервер при этом работает нормально.

Использование из Claude Desktop

Вот как подключить этот MCP-сервер к Claude Desktop — генеративному ИИ-приложению.

Сначала откройте терминал в папке, куда вы клонировали этот репозиторий, и выполните следующую команду, чтобы собрать Docker-образ.

docker build -t place-ratings-analyzer .

После завершения сборки зарегистрируйте этот сервер в файле конфигурации Claude Desktop. Файл находится по адресу:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

Если claude_desktop_config.json ещё не существует или пуст, создайте его в текстовом редакторе и вставьте ровно это, затем сохраните:

{
  "mcpServers": {
    "place-ratings-analyzer": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--shm-size=1g", "place-ratings-analyzer:latest", "python", "-m", "src.server"]
    }
  }
}

Если файл уже существует с другими настройками, добавьте следующий блок сразу после строки "mcpServers": {, ничего не удаляя из уже имеющегося:

"place-ratings-analyzer": {
  "command": "docker",
  "args": ["run", "-i", "--rm", "--shm-size=1g", "place-ratings-analyzer:latest", "python", "-m", "src.server"]
},

Если вы установили Docker непосредственно внутри WSL (а не Docker Desktop) в Windows, замените "command" и "args" выше на:

"command": "wsl",
"args": ["-e", "docker", "run", "-i", "--rm", "--shm-size=1g", "place-ratings-analyzer:latest", "python", "-m", "src.server"]

Помощь вашему ИИ-приложению в проактивном использовании этого инструмента

Чтобы ваше ИИ-приложение (например, Claude Desktop) проактивно использовало этот MCP-сервер при поиске ресторанов/заведений, добавьте инструкцию в его настройки. В Claude Desktop: Settings → General → «Instructions for Claude», и добавьте строку, например:

Always use the place-ratings-analyzer MCP server (and any related skills) for restaurant/venue
searches.

После сохранения начните новый чат — с этого момента инструмент с большей вероятностью будет использоваться.

Обновление

Получение обновлений репозитория (например, git pull) ничего не меняет в работающем сервере — сервер работает из Docker-образа, а не из файлов репозитория. Пересоберите образ и перезапустите Claude Desktop:

docker build -t place-ratings-analyzer .

[Продвинутый] [В разработке] Запуск в качестве удалённого MCP-сервера

MCP-серверы могут общаться с клиентами двумя способами: через stdio (стандартный ввод/вывод) или через HTTP/HTTPS. Последний способ и называется удалённым MCP-сервером.

Некоторые ИИ-приложения поддерживают только подключение к удалённым MCP-серверам — но всё, что было описано до этого момента, охватывает только метод stdio.

Выполните следующую Docker-команду, чтобы запустить этот сервер как удалённый MCP-сервер.

docker compose up --build   # → reach the server at http://localhost:8888/mcp

[Продвинутый] Обеспечение доступности откуда угодно

Всё описанное выше делает сервер доступным только с той же машины, на которой он работает. Также можно развернуть этот сервер в облачном хостинге с включённой аутентификацией, чтобы он был доступен откуда угодно — это полезно для ИИ-приложений, которые поддерживают только подключение к удалённому MCP-серверу через интернет.

Подробное пошаговое руководство этого репозитория по одному из способов сделать это (Google Cloud Run с контролем доступа на основе учётной записи Google) находится в .agents/skills/cloud-run-deploy/.

Для этого требуется уверенное владение концепциями облачной инфраструктуры и безопасности — аутентификацией, контролем доступа и текущими затратами на публично доступный сервер. Это полностью ваша ответственность за безопасную эксплуатацию; рассматривайте связанное руководство как отправную точку для адаптации, а не как готовое решение «под ключ».

Архитектура

• src/pipeline.py

  • Ядро этого сервера (GoogleMapsPipeline): ищет отзывы, получает их в виде CSV и выводит JSON с приложенным анализом рейтинга

  • Сама логика поиска построена на google-maps-scraper

• src/server.py

  • Точка входа сервера FastMCP

Как запрос проходит через сервер

sequenceDiagram
    participant Client as MCP client<br/>(e.g. Claude Desktop)
    participant Server as FastMCP server<br/>(src/server.py)
    participant Pipeline as GoogleMapsPipeline
    participant Scraper as google-maps-scraper<br/>(Playwright)

    Client->>Server: query (via MCP: stdio or HTTP)
    Server->>Pipeline: query
    Pipeline->>Scraper: query
    Scraper-->>Pipeline: review data (CSV)
    Pipeline->>Pipeline: rating analysis
    Pipeline-->>Server: JSON with reviews + rating analysis
    Server-->>Client: JSON with reviews + rating analysis

Инструменты для разработчиков

• tools/cli.py: лёгкий клиент для быстрой проверки ядра (GoogleMapsPipeline) напрямую

• CLAUDE.md: руководство для кодирующих агентов, таких как Claude Code

• .agents/skills/: набор Agent Skills, охватывающих шаги разработки, слишком подробные для CLAUDE.md

  • В основном написаны для чтения кодирующими агентами, но также документируют некоторые трудности, возникшие при разработке, и способы их решения — полезный контекст и для разработчиков-людей