gbp-mcp

Servidor MCP independiente para Google Business Profile. Expone cuentas, ubicaciones, reseñas, publicaciones, medios, preguntas y respuestas, estadísticas y algunas acciones de escritura como herramientas JSON para Cursor, Claude Desktop y Claude Code.

Este repositorio no es la aplicación Streamlit GMB-Management-System. No hay interfaz web, exportación a PDF, gráficos Plotly, panel i18n ni redacción de respuestas Gemini. Las llamadas a la API de Google residen en este repositorio (data_fetcher.py, drive_helper.py). No es necesario clonar ni ejecutar el proyecto Streamlit.

Tools

Lectura:

• list_accounts

• list_locations

• get_daily_metrics

• get_search_keywords

• list_reviews

• list_posts

• list_media

• list_questions

• profile_health_check

Escritura:

• create_local_post

• upload_image_to_drive

• reply_to_review

Ayudantes de autenticación:

• start_oauth

• complete_oauth

Cada herramienta devuelve solo JSON (sin objetos DataFrame, PDF ni gráficos).

Los IDs de ubicación aceptan accounts/{accountId}/locations/{locationId}, locations/{locationId} o un id simple. Las llamadas v4 (reseñas, publicaciones, medios) pasan por resolve_location_parent. Las fechas tienen formato YYYY-MM-DD. Las subidas a Drive toman bytes de imagen en base64 (file_base64) y pueden devolver una URL pública para publicaciones de GBP.

Related MCP server: google-ads-mcp

Requirements

• Python 3.10+

• Un cliente de OAuth de usuario de Google Cloud (Escritorio o Web). No se admiten cuentas de servicio.

• Estos ámbitos de OAuth:

  • https://www.googleapis.com/auth/business.manage

  • https://www.googleapis.com/auth/drive.file

  • https://www.googleapis.com/auth/drive.metadata.readonly

Habilita las API de Google que llamarán tus herramientas, normalmente:

• 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

Copia .env.example y exporta los valores, o colócalos en el bloque env de tu cliente MCP. No subas .env, client_secret.json ni archivos de token.

cp .env.example .env

Authenticate (user OAuth only)

Nunca pongas tokens, tokens de actualización ni client_secret.json en git.

Necesitas un ID de cliente y secreto de OAuth de Google Cloud (GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET). Opcional: coloca un client_secret.json local en la raíz del repositorio (ignorado por git).

Añade esta URI de redirección en el cliente OAuth (a menos que la sobrescribas):

http://localhost:8753/

Luego elige una de las siguientes:

1. Token por llamada — pasa access_token en cualquier herramienta.

2. Token de entorno — establece GOOGLE_ACCESS_TOKEN. Actualización opcional: GOOGLE_REFRESH_TOKEN más id/secreto de cliente.

3. Ayudante local (abre un navegador, escribe un archivo de token ignorado por git, por defecto .gmb-mcp-token.json):

python mcp_server.py --oauth

4. Herramientas MCP — llama a start_oauth, aprueba el acceso, luego complete_oauth con el parámetro de consulta code de la URL de redirección.

complete_oauth y --oauth nunca imprimen tokens. Sobrescribe la ruta del token con GMB_MCP_TOKEN_PATH. Sobrescribe la redirección con GOOGLE_REDIRECT_URI.

Run

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

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

HTTP transmisible opcional:

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

Endpoint: http://127.0.0.1:8765/mcp

Connect from Cursor

Añade a la configuración de MCP (.cursor/mcp.json del proyecto o configuración de MCP del usuario). Usa una ruta absoluta. No pongas tokens en un archivo subido.

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

Si ya tienes un token de acceso de usuario y prefieres no ejecutar --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>"
      }
    }
  }
}

Apunta command al intérprete del venv si no quieres activarlo primero, por ejemplo /absolute/path/to/gbp-mcp/.venv/bin/python.

HTTP en lugar de stdio (inicia el servidor tú mismo primero):

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

Connect from Claude Desktop / Claude Code

Claude Desktop (claude_desktop_config.json) y Claude Code usan la misma forma 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>"
      }
    }
  }
}

Ejecuta python mcp_server.py --oauth una vez en ese directorio de trabajo para que exista .gmb-mcp-token.json, o establece GOOGLE_ACCESS_TOKEN.

Security

• Nunca subas client_secret.json, .env ni .gmb-mcp-token.json.

• Nunca pegues tokens de acceso en chats, issues o capturas de pantalla.

• Las herramientas y ayudantes de OAuth no devuelven tokens.

• Las subidas a Drive con make_public=true crean una URL de archivo legible por todo el mundo. Úsala solo cuando tengas la intención de adjuntar la imagen a una publicación pública de GBP.

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 (consulta LICENSE).