Submit
jikime

py-mcp-google-toolbox

Community jikime
Updated

py-mcp-google-toolbox

smithery badge 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
  • 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

Installing via Smithery

To install py-mcp-google-toolbox for Claude Desktop automatically via Smithery:

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

Local Setup

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

Configure MCP Settings

Add the server configuration to your MCP settings file:

Claude desktop app

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

MCP Server · Populars

MCP Server · New