gbp-mcp

Google Business Profile (https://developers.google.com/my-business) 用のスタンドアロン MCP サーバー です。アカウント、ロケーション、レビュー、投稿、メディア、Q&A、インサイト、およびいくつかの書き込みアクションを JSON ツールとして公開し、Cursor、Claude Desktop、Claude Code で利用できます。

このリポジトリは Streamlit の GMB-Management-System アプリではありません。Web 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 ユーザークライアント (デスクトップまたは Web)。サービスアカウントはサポートされていません。

• 以下の 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, reviews / posts / media で使用)

インストール

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 を仮想環境のインタープリタに指定します。例: /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 を 1 回実行して .gmb-mcp-token.json が存在するようにするか、GOOGLE_ACCESS_TOKEN を設定します。

セキュリティ

• client_secret.json、.env、.gmb-mcp-token.json を絶対にコミットしないでください。

• アクセストークンをチャット、Issue、スクリーンショットに貼り付けないでください。

• ツールと 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 を参照)。