Google Toolbox

Integrations

  • Enables email operations including listing, searching, sending, and modifying emails with support for labels, read/unread status, and archive/trash actions

  • Enables web searches via Google's Custom Search API and returns formatted search results

  • Provides calendar management capabilities for creating, retrieving, updating, and deleting events, with support for attendees, locations, and time ranges

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

  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
  1. Create and activate virtual environment:
uv venv -p 3.12 source .venv/bin/activate # On MacOS/Linux # or .venv\Scripts\activate # On Windows
  1. Install dependencies:
uv pip install -r requirements.txt
  1. 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
  1. 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
  1. 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 .
  1. Run the container:
docker run py-mcp-google-toolbox
Using Local
  1. Run the server:
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
  1. 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

You must be authenticated.

A
security – no known vulnerabilities
F
license - not found
A
quality - confirmed to work

local-only server

The server can only run on the client's local machine because it depends on local resources.

Google Toolbox

  1. Overview
    1. Table of Contents
      1. Prerequisites
        1. Installation
          1. Git Clone
          2. Configuration
          3. Using Docker
          4. Using Local
        2. Configure MCP Settings
          1. Claude desktop app
          2. Cursor IDE
          3. for Docker
        3. Tools Documentation
          1. Gmail Tools
          2. Calendar Tools
          3. Drive Tools
          4. Search Tools
        4. Development
          1. License

            Related MCP Servers

            • -
              security
              A
              license
              -
              quality
              Integrates with Google Tasks to allow listing, reading, searching, creating, updating, and deleting tasks.
              Last updated -
              15
              TypeScript
              MIT License
            • -
              security
              F
              license
              -
              quality
              Enables managing Google Cloud Platform resources through natural language commands in Claude Desktop, supporting comprehensive operations across compute, storage, databases, networking, monitoring, and IAM without manual credential setup.
              Last updated -
              8
              Python
              • Apple
            • -
              security
              A
              license
              -
              quality
              A tool that connects Google Ads with Claude AI, allowing users to analyze advertising data through natural language conversations and access campaign information, performance metrics, keyword analytics, and ad management.
              Last updated -
              60
              Python
              MIT License
              • Apple
            • -
              security
              A
              license
              -
              quality
              Enables AI assistants to interact with and manage Google Cloud Platform resources including Compute Engine, Cloud Run, Storage, BigQuery, and other GCP services through a standardized MCP interface.
              Last updated -
              1
              Python
              MIT License
              • Linux
              • Apple

            View all related MCP servers

            ID: 4wfavu4bhs