place-ratings-analyzer

일본어 버전: README_ja.md

Google Maps 리뷰 평점을 가져와 분석하는 MCP 서버입니다. 단순히 평균 별점만이 아니라 ★1~★5 전체 개수 분포를 제공합니다. Claude Desktop과 같은 AI 앱과 함께 사용하세요.

이 도구는 무엇을 위한 것인가?

Claude Desktop과 같은 AI 앱은 이미 레스토랑의 평판을 숫자로 보여줄 수 있습니다. 예를 들어 "★4.0 평균" 같은 식입니다. 하지만 그 숫자만으로는 평점이 ★4 주변에 모여 있는지, 아니면 ★5와 ★1로 갈려 있는지 알 수 없습니다. 이 서버는 Google Maps에서 특정 장소의 리뷰를 조회하여 실제 별점별 개수 분포를 얻고, 그 패턴을 바탕으로 평가를 제공합니다. 이 서버를 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에서 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 앱이 이 도구를 적극적으로 사용하도록 돕기

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 방식만 다루었습니다.

이 서버를 원격 MCP 서버로 실행하려면 다음 Docker 명령을 실행하세요.

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 모음입니다.

  • 주로 코딩 에이전트가 읽도록 작성되었지만, 개발 중 겪은 문제와 해결 방법도 문서화되어 있어 인간 개발자에게도 유용한 배경 지식을 제공합니다.