What is Py Mcp Google Toolbox

py-mcp-google-toolbox is an MCP server that provides AI assistants with powerful tools to interact with various Google services, including Gmail, Google Calendar, Google Drive, and Google Search.

Use cases

Use cases include automating email management, scheduling events in Google Calendar, managing files in Google Drive, and performing web searches directly from an AI assistant.

How to use

To use py-mcp-google-toolbox, ensure you have Python 3.12 or higher installed. Set up a project in Google Cloud Console, enable the necessary APIs, and configure OAuth 2.0 credentials. Follow the installation instructions in the README to get started.

Key features

Key features include Gmail operations (reading, searching, sending, modifying emails), Google Calendar management (creating, listing, updating, deleting events), Google Drive interactions (searching and reading files), and integration with Google Search for web queries.

Where to use

py-mcp-google-toolbox can be used in various fields such as personal productivity, business automation, and any application requiring interaction with Google services for enhanced efficiency.

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)

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:[email protected]"

# Example: Send email
uv run client.py send_email to="[email protected]" 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="[email protected],[email protected]"

# 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="[email protected],[email protected]"

# 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