Skip to content

setup.md

Latest commit

 

History

History
211 lines (159 loc) · 5.92 KB

setup.md

File metadata and controls

211 lines (159 loc) · 5.92 KB

Complete Setup Guide

This guide walks you through setting up the Google MCP Server with detailed Google Cloud Console configuration.

Prerequisites

  • Python 3.12 or higher
  • uv for dependency management
  • A Google account
  • Claude Desktop or MCP-compatible client

Google Cloud Console Setup

Step 1: Create a Google Cloud Project

  1. Go to the Google Cloud Console
  2. Click on the project selector dropdown (top-left, next to "Google Cloud")
  3. Click "New Project"
  4. Enter a project name (e.g., "claude-google-integration")
  5. Select your organization (if applicable)
  6. Click "Create"
  7. Wait for the project to be created and make sure it's selected

Step 2: Enable Required APIs

  1. In the Google Cloud Console, navigate to "APIs & Services" > "Library"
  2. Search for and enable the following APIs (click on each, then click "Enable"):
    • Google Drive API
    • Gmail API
    • Google Calendar API
    • People API (for contacts and user profile information)

Step 3: Configure OAuth Consent Screen

  1. Go to "APIs & Services" > "OAuth consent screen"
  2. Choose "External" user type (unless you're using Google Workspace)
  3. Click "Create"
  4. Fill in the required information:
    • App name: Choose a name (e.g., "Claude Google Integration")
    • User support email: Your email address
    • Developer contact information: Your email address
  5. Click "Save and Continue"
  6. On the "Scopes" page, click "Save and Continue" (we'll add scopes in our application)
  7. On the "Test users" page, add your email address to test the integration
  8. Click "Save and Continue"
  9. Review and click "Back to Dashboard"

Step 4: Create OAuth2 Credentials

  1. Go to "APIs & Services" > "Credentials"
  2. Click "Create Credentials" > "OAuth client ID"
  3. Choose "Desktop application" as the application type
  4. Enter a name (e.g., "Google MCP Server")
  5. Click "Create"
  6. A dialog will appear with your client ID and client secret
  7. Important: Copy both the Client ID and Client Secret - you'll need these for the MCP server

Step 5: Configure Authorized Redirect URIs (if needed)

  1. In the Credentials page, click on your newly created OAuth client ID
  2. Under "Authorized redirect URIs", add: http://localhost:8080
  3. Click "Save"

Note: The default redirect URI is http://localhost:8080. If you need to use a different port, make sure to update both the Google Cloud Console configuration and your .env file.

Installation

# Clone or download the repository
git clone https://github.com/robcerda/google-mcp-server
cd google-mcp-server

# Install dependencies with uv
uv sync

# Test the server works
uv run python test_cli.py

Configuration

1. Create Environment File

Copy the example environment file and configure your Google OAuth2 credentials:

cp .env.example .env

Edit the .env file with your Google Cloud Console credentials:

# Google OAuth2 Configuration
GOOGLE_CLIENT_ID=your_client_id_here.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your_client_secret_here

# Optional: Custom redirect URI (defaults to http://localhost:8080)
# GOOGLE_REDIRECT_URI=http://localhost:8080

# Optional: Additional scopes (space-separated)
# GOOGLE_ADDITIONAL_SCOPES=https://www.googleapis.com/auth/spreadsheets

2. Configure Claude Desktop

Add the server to your Claude Desktop configuration file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\\Claude\\claude_desktop_config.json

{
  "mcpServers": {
    "google-services": {
      "command": "/path/to/google-mcp-server/.venv/bin/mcp",
      "args": [
        "run",
        "/path/to/google-mcp-server/server.py"
      ]
    }
  }
}

Example with full path:

{
  "mcpServers": {
    "google-services": {
      "command": "/Users/rob/Scripts/google-mcp-server/.venv/bin/mcp",
      "args": [
        "run",
        "/Users/rob/Scripts/google-mcp-server/server.py"
      ]
    }
  }
}

Alternative using uv (if MCP path issues):

{
  "mcpServers": {
    "google-services": {
      "command": "/opt/homebrew/bin/uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "mcp",
        "run",
        "/Users/rob/Scripts/google-mcp-server/server.py"
      ],
      "cwd": "/Users/rob/Scripts/google-mcp-server"
    }
  }
}

Note: Use the full path to uv (find yours with which uv) to ensure Claude Desktop can locate it.

3. Test the Server

Before using with Claude Desktop, test the server:

# Test authentication and API access
uv run python test_cli.py

# Test the MCP server directly 
uv run mcp run server.py

First Run Authentication

When you first use the server, it will automatically launch your browser for OAuth2 authentication:

  1. The server will open your default browser
  2. Sign in to your Google account
  3. Grant the requested permissions
  4. The browser will redirect to a success page
  5. Return to Claude - you're now authenticated!

Your credentials will be securely stored locally in ~/.config/google-mcp-server/token.json.

Advanced Configuration

Custom OAuth2 Scopes

You can add additional Google API scopes by setting the GOOGLE_ADDITIONAL_SCOPES environment variable:

GOOGLE_ADDITIONAL_SCOPES=https://www.googleapis.com/auth/spreadsheets https://www.googleapis.com/auth/contacts

Custom Redirect URI

If you need to use a different port for the OAuth2 callback:

GOOGLE_REDIRECT_URI=http://localhost:9000

Make sure to update the authorized redirect URIs in your Google Cloud Console accordingly.

Security

  • Local Storage: Credentials are stored locally in ~/.config/google-mcp-server/
  • Token Refresh: Access tokens are automatically refreshed using stored refresh tokens
  • Scope Limitation: Only request the minimum required scopes for functionality
  • No Server Storage: No credentials or tokens are sent to external servers