place-ratings-analyzer

日本語版: README_ja.md

Googleマップのレビュー評価を取得して分析するMCPサーバー — 平均星評価だけでなく、★1〜★5の完全な内訳も取得します。Claude DesktopなどのAIアプリと一緒に使ってください。

このツールは何のためにあるのか？

Claude DesktopなどのAIアプリは、レストランの評判を「★4.0平均」のような数字で表示することはできます。しかし、その数字だけでは、評価が★5に集中しているのか、★5と★1に分かれているのかはわかりません。このサーバーは、Googleマップ上の場所のレビューを取得し、実際の星ごとの内訳を提示し、そのパターンに基づいた評価を提供します。このサーバーをAIアプリに接続すれば、特定の場所の評判を詳しく調べたり、評価が分かれている場所を見つけたりすることができます。

Related MCP server: Local Business Data MCP Server

インストール

このサーバーのインストールには、ある程度のコンピューター知識が必要です。以下の内容で不明な点があれば、このファイルをAIアプリに見せて質問してみてください。あるいは、エージェント機能（Coworkなど）を使ってインストールを進めることも検討してください。

必要条件

• このサーバーはDocker上で動作します。

  • Windowsの場合、DockerにはWSLが必要です。まだWSLがない場合は、PowerShell（または類似のターミナル）を管理者として開き、以下を実行してください：

    • wsl --install

  • これでWSLと必要なものがすべて一括でインストールされます。完了したら、Windowsを再起動してください。

  • 再起動後、スタートメニューから「Ubuntu」を開きます。初回起動時に、Linuxのユーザー名とパスワードの作成を求められます — 好きなものを設定してください。

• Docker自体のインストール方法は2つあります：

  1. Docker Desktopをインストールする。

     • こちらが簡単な方法です。

     • 商用利用（例：会社で使う場合）の場合は、ライセンス条件を確認してください — 状況によっては有料プランが必要です。

  2. コマンドラインからUbuntuや他のLinux環境にインストールする。

     • Docker Desktopとは異なり、こちらは商用利用でも無料です。以下を実行してください：

     • sudo apt install -y docker.io

     • 環境によっては、このコマンドに加えて追加の設定が必要な場合があります（例：Dockerの公式aptリポジトリを追加するなど）。詳しくはウェブやDockerのドキュメントを参照してください。

リポジトリのダウンロード

• git cloneを使うか、このリポジトリのページからZIPファイルとしてダウンロードしてください。

• Windowsでファイルを正しくクローンするには、Windows Developer Modeを有効にして、git cloneに次のオプションを追加してください：

  • -c core.symlinks=true

  • このオプションがないと、プロジェクトの開発者向け機能（Agent Skills）の一部が制限されます — サーバー自体は通常どおり動作します。

Claude Desktopから使う

このMCPサーバーをClaude Desktop（生成AIアプリ）に接続する手順は次のとおりです。

まず、このリポジトリをクローンしたフォルダーでターミナルを開き、以下のコマンドを実行して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"]
},

WindowsでDocker DesktopではなくWSL内に直接Dockerをインストールした場合は、上記の"command"と"args"を次のように置き換えてください：

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

AIアプリがこのツールを自発的に使えるようにする

Claude DesktopなどのAIアプリが、レストランや場所の検索時にこのMCPサーバーを自発的に使うようにするには、アプリの設定に指示を追加します。Claude Desktopの場合：設定 → 一般 → 「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サーバーは2つの方法でクライアントと通信できます：標準入出力（stdio）、またはHTTP/HTTPS経由です。後者は「リモートMCPサーバー」と呼ばれます。

一部のAIアプリはリモートMCPサーバーへの接続のみをサポートしています — しかし、ここまでの説明はすべてstdio方式のものです。

次のDockerコマンドを実行すると、このサーバーをリモートMCPサーバーとして実行できます：

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

[上級] どこからでもアクセスできるようにする

ここまでの手順では、サーバーは同じマシンからしかアクセスできません。クラウドホストにデプロイして認証を有効にすれば、どこからでもアクセスできるようになります — リモートMCPサーバーへの接続のみをサポートするAIアプリにとって有用です。

このリポジトリには、その方法（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/: CLAUDE.mdに記載するには詳細すぎる開発手順をまとめたAgent Skillsのセットです。

  • 主にコーディングエージェントが読むことを想定していますが、開発中に遭遇した問題とその解決方法の背景も記録されており、人間の開発者にも役立ちます。