gbp-mcp

Standalone MCP server for Google Business Profile. It exposes accounts, locations, reviews, posts, media, Q&A, insights, and a few write actions as JSON tools for Cursor, Claude Desktop, and Claude Code.

This repository is not the Streamlit GMB-Management-System app. There is no web UI, PDF export, Plotly charts, i18n dashboard, or Gemini reply drafting. Google API calls live in this repo (data_fetcher.py, drive_helper.py). You do not need to clone or run the Streamlit project.

Tools

Read:

• list_accounts
• list_locations
• get_daily_metrics
• get_search_keywords
• list_reviews
• list_posts
• list_media
• list_questions
• profile_health_check

Write:

• create_local_post
• upload_image_to_drive
• reply_to_review

Auth helpers:

• start_oauth
• complete_oauth

Every tool returns JSON only (no DataFrame, PDF, or chart objects).

Location IDs accept accounts/{accountId}/locations/{locationId}, locations/{locationId}, or a bare id. v4 calls (reviews, posts, media) go through resolve_location_parent. Dates are YYYY-MM-DD. Drive uploads take base64 image bytes (file_base64) and can return a public URL for GBP posts.

Requirements

• Python 3.10+
• A Google Cloud OAuth user client (Desktop or Web). Service accounts are not supported.
• These OAuth scopes:
  • https://www.googleapis.com/auth/business.manage
  • https://www.googleapis.com/auth/drive.file
  • https://www.googleapis.com/auth/drive.metadata.readonly

Enable the Google APIs your tools will call, typically:

• 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, used for reviews / posts / media)

Install

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

Copy .env.example and export the values, or put them in your MCP client env block. Do not commit .env, client_secret.json, or token files.

cp .env.example .env

Authenticate (user OAuth only)

Never put tokens, refresh tokens, or client_secret.json in git.

You need a Google Cloud OAuth client ID and secret (GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET). Optional: place a local client_secret.json in the repo root (gitignored).

Add this redirect URI on the OAuth client (unless you override it):

http://localhost:8753/

Then pick one of:

1. Per-call token — pass access_token on any tool.
2. Environment token — set GOOGLE_ACCESS_TOKEN. Optional refresh: GOOGLE_REFRESH_TOKEN plus client id/secret.
3. Local helper (opens a browser, writes a gitignored token file, default .gmb-mcp-token.json):

python mcp_server.py --oauth

4. MCP tools — call start_oauth, approve access, then complete_oauth with the code query parameter from the redirect URL.

complete_oauth and --oauth never print tokens. Override the token path with GMB_MCP_TOKEN_PATH. Override the redirect with GOOGLE_REDIRECT_URI.

Run

stdio (default — Cursor, Claude Desktop, Claude Code):

python mcp_server.py
# or: python -m src.gmb_mcp

Optional Streamable HTTP:

python mcp_server.py --http --host 127.0.0.1 --port 8765

Endpoint: http://127.0.0.1:8765/mcp

Connect from Cursor

Add to MCP settings (project .cursor/mcp.json or user MCP config). Use an absolute path. Do not put tokens in a committed file.

{
  "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>"
      }
    }
  }
}

If you already have a user access token and prefer not to run --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>"
      }
    }
  }
}

Point command at the venv interpreter if you do not want to activate it first, for example /absolute/path/to/gbp-mcp/.venv/bin/python.

HTTP instead of stdio (start the server yourself first):

{
  "mcpServers": {
    "google-business-profile": {
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

Connect from Claude Desktop / Claude Code

Claude Desktop (claude_desktop_config.json) and Claude Code use the same stdio shape:

{
  "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>"
      }
    }
  }
}

Run python mcp_server.py --oauth once in that working directory so .gmb-mcp-token.json exists, or set GOOGLE_ACCESS_TOKEN.

Security

• Never commit client_secret.json, .env, or .gmb-mcp-token.json.
• Never paste access tokens into chat, issues, or screenshots.
• Tools and OAuth helpers do not return tokens.
• Drive uploads with make_public=true create a world-readable file URL. Use that only when you intend to attach the image to a public GBP post.

Development

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

License

MIT (see LICENSE).