Google Business Profile Review MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to manage Google Business Profile reviews through intelligent automation.

Features

• Review Management: Fetch and analyze Google Business Profile reviews
• AI-Powered Responses: Generate contextually appropriate replies using LLM sampling
• Automated Posting: Post replies back to Google Business Profile
• OAuth Integration: Secure authentication with Google APIs
• Rate Limiting: Respectful API usage with built-in rate limiting
• Structured Logging: Comprehensive logging for debugging and monitoring

Prerequisites

• Node.js 18.0.0 or higher
• Google Cloud Platform account with My Business API enabled
• Google OAuth 2.0 credentials
• Google Business Profile API Access (see requirements below)

Google Business Profile API Access Requirements

Before you can use this MCP server, you must request and be approved for Google Business Profile API access. Google requires all applicants to:

1. Manage a verified Google Business Profile that has been active for 60+ days
   • This can be your own business or a client's business you manage
2. Have a website representing the business listed on the Google Business Profile
3. Complete Google Business Profile with current, up-to-date information

To request API access:

1. Go to the Google Cloud Console and note your Project Number from the Project info card
2. Submit your request using the GBP API contact form
   • Select "Application for Basic API Access" from the dropdown
   • Provide your Project Number and all requested information
   • Use an email address listed as an owner/manager on your business's GBP
3. Wait for review - you'll receive a follow-up email with the decision

Check approval status by viewing quotas in Google Cloud Console:

• 0 QPM (Queries Per Minute) = Not yet approved
• 300 QPM = Approved ✓

For complete prerequisites, see the official GBP API documentation.

Setup

1. Google Cloud Configuration

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Request GBP API access (see requirements above - this step is critical and may take time for approval)
4. Enable the following APIs (after your project is approved):
   • Go to "APIs & Services" > "Library"
   • Search for and enable "Google My Business API"
   • Search for and enable "My Business Account Management API"
5. Create OAuth 2.0 credentials:
   • Go to "Credentials" in the API & Services section
   • Click "Create Credentials" > "OAuth 2.0 Client IDs"
   • Set application type to "Web application"
   • Add authorized redirect URI: http://localhost:3000/auth/callback
   • Note down the Client ID and Client Secret
6. Configure OAuth Consent Screen:
   • Go to "APIs & Services" > "OAuth consent screen"
   • Add test users (your Google account email that has access to the business profile)
   • Add required scopes: business.manage, userinfo.email, userinfo.profile

2. Installation

# Clone the repository
git clone <repository-url>
cd review-mcp

# Install dependencies
npm install

# Build the project
npm run build

3. Configuration

# Copy the environment template
cp .env.example .env

# Edit .env with your credentials
# Add your Google OAuth credentials and other settings

Required environment variables:

• GOOGLE_CLIENT_ID: Your Google OAuth 2.0 Client ID
• GOOGLE_CLIENT_SECRET: Your Google OAuth 2.0 Client Secret
• GOOGLE_REDIRECT_URI: OAuth redirect URI (default: http://localhost:3000/auth/callback)

4. Authentication

Before running the server, you need to authenticate with Google:

# Run the authentication helper
npm run auth

This will:

1. Open your browser to Google's authentication page
2. Ask you to grant permissions to access your Google Business Profile
3. Save the authentication tokens locally
4. These tokens will be automatically used by the MCP server

5. Running the Server

# Start the server with your authenticated credentials
npm start

# Or in development/mock mode for testing
npm run start:mock

The server will start with STDIO transport for MCP communication.

Usage

Connecting to MCP Clients

You can connect to this server using any MCP-compatible client:

VS Code (GitHub Copilot)

Add to your VS Code MCP settings file (mcp.json):

Windows: %APPDATA%\Code\User\profiles\<profile-id>\mcp.json
macOS/Linux: ~/.config/Code/User/profiles/<profile-id>/mcp.json

{
  "servers": {
    "google-business-reviews": {
      "type": "stdio",
      "command": "node",
      "args": [
        "C:\\path\\to\\review-mcp\\build\\index.js"
      ],
      "cwd": "C:\\path\\to\\review-mcp",
      "env": {
        "NODE_ENV": "production",
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret",
        "GOOGLE_REDIRECT_URI": "http://localhost:3000/auth/callback",
        "LOG_LEVEL": "info"
      },
      "description": "Google Business Profile Review MCP Server - Manage reviews with AI-powered responses"
    }
  }
}

Important Notes:

• Replace C:\\path\\to\\review-mcp with the actual path to your project
• Use double backslashes (\\) in Windows paths
• Replace your-client-id and your-client-secret with your actual OAuth credentials
• Make sure to run npm run auth first to authenticate before using in VS Code
• Restart VS Code after adding the configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "google-business-reviews": {
      "command": "node",
      "args": ["/path/to/review-mcp/build/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret",
        "GOOGLE_REDIRECT_URI": "http://localhost:3000/auth/callback"
      }
    }
  }
}

HTTP Clients

Connect to: http://localhost:3000/mcp

Available Tools

1. list_locations: Get all business locations associated with your account
2. get_reviews: Fetch reviews for a specific location
3. generate_reply: Generate an AI response to a review
4. post_reply: Post a reply to a review on Google Business Profile

Available Resources

1. business_profile: Business profile information and settings
2. review_templates: Pre-defined response templates

Available Prompts

1. review_response: Generate professional review responses
2. sentiment_analysis: Analyze review sentiment

Development

Project Structure

src/
├── index.ts              # Main server entry point
├── server/               # MCP server implementation
│   ├── mcpServer.ts     # Core MCP server setup
│   ├── tools/           # Tool implementations
│   ├── resources/       # Resource implementations
│   └── prompts/         # Prompt implementations
├── services/            # Business logic services
│   ├── googleAuth.ts    # Google OAuth handling
│   ├── reviewService.ts # Review management
│   └── llmService.ts    # LLM interaction
├── types/               # TypeScript type definitions
└── utils/               # Utility functions

Scripts

• npm run dev: Start development server with hot reload
• npm run build: Build the TypeScript project
• npm run lint: Run ESLint
• npm run test: Run tests
• npm run clean: Clean build directory

API Documentation

Authentication Flow

1. User initiates OAuth flow through the MCP client
2. Server redirects to Google OAuth consent screen
3. User grants permissions for Google My Business access
4. Server receives authorization code and exchanges for access token
5. Token is stored securely for subsequent API calls

Rate Limiting

The server implements rate limiting to respect Google API quotas:

• 60 requests per minute per user (configurable)
• Exponential backoff for failed requests
• Graceful error handling for quota exceeded

Security Considerations

• All Google API calls use OAuth 2.0 authentication
• Access tokens are stored securely and refreshed automatically
• Input validation and sanitization for all user inputs
• Rate limiting to prevent abuse
• Comprehensive logging for security monitoring

Troubleshooting

Common Issues

1. OAuth Error: Ensure redirect URI matches exactly what's configured in Google Cloud Console
2. API Quota Exceeded: Check your Google Cloud Console for API usage and limits
3. Permission Denied: Verify the Google account has access to the business profile

Logging

Enable debug logging by setting LOG_LEVEL=debug in your .env file.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

1. Check the troubleshooting section
2. Review the logs with debug level enabled
3. Open an issue on GitHub with detailed information about the problem