Skip to main content
Glama

Google Toolbox

py-mcp-google-toolbox

Version License

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 run server.py
  1. 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
  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

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jikime/py-mcp-google-toolbox'

If you have feedback or need assistance with the MCP directory API, please join our Discord server