gbp-mcp

독립형 MCP 서버 for Google Business Profile. 계정, 위치, 리뷰, 게시물, 미디어, Q&A, 인사이트 및 몇 가지 쓰기 작업을 Cursor, Claude Desktop 및 Claude Code용 JSON 도구로 노출합니다.

이 저장소는 Streamlit GMB-Management-System 앱이 아닙니다. 웹 UI, 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 또는 차트 객체 없음).

위치 ID는 accounts/{accountId}/locations/{locationId}, locations/{locationId} 또는 단순 ID를 허용합니다. v4 호출(리뷰, 게시물, 미디어)은 resolve_location_parent를 통해 처리됩니다. 날짜는 YYYY-MM-DD 형식입니다. Drive 업로드는 base64 이미지 바이트(file_base64)를 사용하며 GBP 게시물에 사용할 공개 URL을 반환할 수 있습니다.

Related MCP server: google-ads-mcp

요구 사항

• Python 3.10+

• Google Cloud OAuth 사용자 클라이언트(데스크톱 또는 웹). 서비스 계정은 지원되지 않습니다.

• 다음 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을 복사하고 값을 내보내거나 MCP 클라이언트 env 블록에 넣으세요. .env, client_secret.json 또는 토큰 파일을 커밋하지 마세요.

cp .env.example .env

인증 (사용자 OAuth만)

토큰, 갱신 토큰 또는 client_secret.json을 git에 절대 넣지 마세요.

Google Cloud OAuth 클라이언트 ID와 시크릿(GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET)이 필요합니다. 선택 사항: 로컬 client_secret.json을 저장소 루트에 배치합니다(gitignore 처리됨).

OAuth 클라이언트에 다음 리디렉션 URI를 추가하세요(재정의하지 않는 한):

http://localhost:8753/

그런 다음 다음 중 하나를 선택하세요:

1. 호출별 토큰 — 모든 도구에 access_token을 전달합니다.

2. 환경 토큰 — GOOGLE_ACCESS_TOKEN을 설정합니다. 선택적 갱신: GOOGLE_REFRESH_TOKEN과 클라이언트 ID/시크릿.

3. 로컬 도우미 (브라우저를 열고 gitignore 처리된 토큰 파일(기본값 .gmb-mcp-token.json)을 작성합니다):

python mcp_server.py --oauth

4. MCP 도구 — start_oauth를 호출하고 액세스를 승인한 다음 리디렉션 URL의 code 쿼리 매개변수로 complete_oauth를 호출합니다.

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

엔드포인트: 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.

stdio 대신 HTTP(먼저 서버를 직접 시작):

{
  "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을 절대 커밋하지 마세요.

• 액세스 토큰을 채팅, 이슈 또는 스크린샷에 절대 붙여넣지 마세요.

• 도구 및 OAuth 도우미는 토큰을 반환하지 않습니다.

• make_public=true로 Drive 업로드하면 전 세계에서 읽을 수 있는 파일 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 참조).