place-ratings-analyzer

日本語版: README_ja.md

一个 MCP 服务器，用于获取并分析 Google 地图的评论评分——不仅仅是平均星级，而是 ★1–★5 的完整数量分布。可配合 Claude Desktop 等 AI 应用一起使用。

这个工具是做什么的？

Claude Desktop 等 AI 应用已经可以向你展示一家餐厅的口碑，比如"平均 ★4.0"。但仅凭这个数字，你无法判断评分是集中在 ★4 附近，还是分裂在 ★5 和 ★1 之间。这个服务器会在 Google 地图上查找某个地点的评论，获取逐星级的实际分布，然后基于该分布模式给出评估。将这个服务器连接到你的 AI 应用后，它就能为你进行更深入的调查——比如核查某个具体地点的口碑，或找出评分存在分裂的地点。

Related MCP server: Local Business Data MCP Server

安装

安装这个服务器需要一定的计算机操作知识。如果下面有任何不清楚的地方，可以尝试把本文件展示给 AI 应用并提问，或者考虑使用 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

     • 根据你的环境，可能还需要在此命令之外进行额外设置（例如添加 Docker 官方的 apt 仓库）。详情请参阅网络或 Docker 的文档。

下载仓库

• 可以通过 git clone 下载，也可以从本仓库页面下载 ZIP 文件。

• 要在 Windows 上正确克隆所有文件，请开启 Windows 开发者模式，并在 git clone 中添加以下选项：

  • -c core.symlinks=true

  • 如果不加，项目中面向开发者的部分功能（Agent Skills）会受限——但服务器本身仍可正常运行。

从 Claude Desktop 使用

下面介绍如何将这个 MCP 服务器连接到生成式 AI 应用 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"]
},

如果你在 Windows 上直接安装在 WSL 内部（而非 Docker Desktop），请将上面的 "command" 和 "args" 替换为：

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

帮助你的 AI 应用主动使用此工具

为了让你的 AI 应用（例如 Claude Desktop）在搜索餐厅/场所时主动使用这个 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 服务器可以通过两种方式与客户端通信：通过 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/：一组 Agent Skills，涵盖对 CLAUDE.md 来说过于详细的开发步骤

  • 主要供编码代理阅读，但也记录了开发过程中遇到的一些问题及其解决方法——这些背景信息对人类开发者同样有用