py-mcp-google-toolbox

An MCP server that provides AI assistants with powerful tools to interact with Google services, including Gmail, Google Calendar, Google Drive, and Google Search.

Overview

py-mcp-google-toolbox provides the following Google-related functionalities:

• Gmail operations (read, search, send, modify)

• Google Calendar management (events creation, listing, updating, deletion)

• Google Drive interactions (search, read files)

• Google Search integration (search web)

Related MCP server: Google Workspace MCP Server

Table of Contents

• Prerequisites

• Installation

• Configure MCP Settings

• Tools Documentation

  • Gmail Tools

  • Calendar Tools

  • Drive Tools

  • Search Tools

• Development

• License

Prerequisites

1. Python: Install Python 3.12 or higher

2. Google Cloud Console Setup:

   • Go to Google Cloud Console

   • Create a new project or select an existing one

   • Enable the Service API:

     1. Go to "APIs & Services" > "Library"

     2. Search for and enable "Gmail API"

     3. Search for and enable "Google Calendar API"

     4. Search for and enable "Google Drive API"

     5. Search formand enable "Custom Search API"

   • Set up OAuth 2.0 credentials from GCP:

     1. Go to "APIs & Services" > "Credentials"

     2. Click "Create Credentials" > "OAuth client ID"

     3. Choose "Web application"

     4. Note down the Client ID and Client Secret

        • Client ID

        • Client Secret

     5. download secret json and rename to credentials.json

   • Generate an API key

3. Go to Custom Search Engine and get its ID

Installation

Git Clone

git clone https://github.com/jikime/py-mcp-google-toolbox.git
cd py-mcp-google-toolbox

Configuration

1. Install UV package manager:

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Create and activate virtual environment:

uv venv -p 3.12
source .venv/bin/activate  # On MacOS/Linux
# or
.venv\Scripts\activate  # On Windows

3. Install dependencies:

uv pip install -r requirements.txt

4. Get refresh token (if token is expired, you can run this)

uv run get_refresh_token.py

This will:

• Open your browser for Google OAuth authentication

• Request the following permissions:

  • https://www.googleapis.com/auth/gmail.modify

  • https://www.googleapis.com/auth/calendar

  • https://www.googleapis.com/auth/gmail.send

  • https://www.googleapis.com/auth/gmail.readonly

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

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

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

• Save the credentials to token.json

• Display the refresh token in the console

5. Environment variables:

cp env.example .env
vi .env
# change with your key
GOOGLE_API_KEY=your_google_api_key
GOOGLE_CSE_ID=your_custom_search_engine_id
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GOOGLE_REFRESH_TOKEN=your_google_refresh_token

6. copy credentials.json to project root folder (py-mcp-google-toolbox)

Using Docker

1. Build the Docker image:

docker build -t py-mcp-google-toolbox .

2. Run the container:

docker run py-mcp-google-toolbox

Using Local

1. Run the server:

mcp run server.py

2. Run the MCP Inspector

mcp dev server.py

Configure MCP Settings

Add the server configuration to your MCP settings file:

Claude desktop app

1. To install automatically via Smithery:

npx -y @smithery/cli install @jikime/py-mcp-google-toolbox --client claude

2. To install manually open ~/Library/Application Support/Claude/claude_desktop_config.json

Add this to the mcpServers object:

{
  "mcpServers": {
    "Google Toolbox": {
      "command": "/path/to/bin/uv",
      "args": [
        "--directory",
        "/path/to/py-mcp-google-toolbox",
        "run",
        "server.py"
      ]
    }
  }
}

Cursor IDE

open ~/.cursor/mcp.json

Add this to the mcpServers object:

{
  "mcpServers": {
    "Google Toolbox": {
      "command": "/path/to/bin/uv",
      "args": [
        "--directory",
        "/path/to/py-mcp-google-toolbox",
        "run",
        "server.py"
      ]
    }
  }
}

for Docker

{
  "mcpServers": {
    "Google Toolbox": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "py-mcp-google-toolbox"
      ]
    }
  }
}

Tools Documentation

Gmail Tools

• list_emails: Lists recent emails from Gmail inbox with filtering options

• search_emails: Performs advanced Gmail searches with detailed email content retrieval

• send_email: Composes and sends emails with support for CC, BCC recipients

• modify_email: Changes email states (read/unread, archived, trashed) by modifying labels

Calendar Tools

• list_events: Retrieves upcoming calendar events within specified time ranges

• create_event: Creates new calendar events with attendees, location, and description

• update_event: Modifies existing calendar events with flexible parameter updating

• delete_event: Removes calendar events by event ID

Drive Tools

• read_gdrive_file: Reads and retrieves content from Google Drive files

• search_gdrive: Searches Google Drive for files with customizable queries

Search Tools

• search_google: Performs Google searches and returns formatted results

Development

For local testing, you can use the included client script:

# Example: List emails
uv run client.py list_emails max_results=5 query="is:unread"

# Example: Search emails
uv run client.py search_emails query="from:test@example.com"

# Example: Send email
uv run client.py send_email to="test@example.com" subject="test mail" body="Hello"

# Example: Modify email
uv run client.py modify_email id=MESSAGE_ID remove_labels=INBOX add_labels=ARCHIVED

# Example: List events
uv run client.py list_events time_min=2025-05-01T00:00:00+09:00 time_max=2025-05-02T23:59:59+09:00 max_results=5

# Example: Create event
uv run client.py create_event summary="new event" start=2025-05-02T10:00:00+09:00 end=2025-05-02T11:00:00+09:00 attendees="user1@example.com,user2@example.com"

# Example: Update event
uv run client.py update_event event_id=EVENT_ID summary="update event" start=2025-05-02T10:00:00+09:00 end=2025-05-02T11:00:00+09:00 attendees="user1@example.com,user2@example.com"

# Example Delete event
uv run client.py delete_event event_id=EVENT_ID

# Example: Search Google
uv run client.py search_google query="what is the MCP?"

# Example: Search Google Drive
uv run client.py search_gdrive query=mcp

# Example: Read file
uv run client.py read_gdrive_file file_id=1234567890

License

MIT License