gbp-mcp

独立的 MCP 服务器，用于 Google Business Profile。它将账号、地点、评论、帖子、媒体、问答、数据洞察以及少量写入操作作为 JSON 工具暴露给 Cursor、Claude Desktop 和 Claude Code。

此仓库 不是 Streamlit 应用 GMB-Management-System。没有 Web 界面、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 发现，用于评论/帖子/媒体）

安装

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。

使用 HTTP 替代 stdio（先自行启动服务器）：

{
  "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）。