py-mcp-google-toolbox

insignia de herrería Versión Licencia

Un servidor MCP que proporciona a los asistentes de IA herramientas potentes para interactuar con los servicios de Google, incluidos Gmail, Google Calendar, Google Drive y Google Search.

Descripción general

py-mcp-google-toolbox proporciona las siguientes funcionalidades relacionadas con Google:

Operaciones de Gmail (leer, buscar, enviar, modificar)
Gestión de Google Calendar (creación, listado, actualización y eliminación de eventos)
Interacciones de Google Drive (búsqueda, lectura de archivos)
Integración de Búsqueda de Google (búsqueda web)

Related MCP server: Algolia

Tabla de contenido

Prerrequisitos

Python : Instale Python 3.12 o superior
Configuración de la consola de Google Cloud :
- Ir a la consola de Google Cloud
- Crea un nuevo proyecto o selecciona uno existente
- Habilitar la API de servicio:
  1. Vaya a "API y servicios" > "Biblioteca".
  2. Busque y habilite "API de Gmail"
  3. Busque y habilite "API de Google Calendar"
  4. Busque y habilite "API de Google Drive"
  5. Formulario de búsqueda y habilitación de la "API de búsqueda personalizada"
- Configurar las credenciales de OAuth 2.0 desde GCP:
  1. Vaya a "API y servicios" > "Credenciales".
  2. Haga clic en "Crear credenciales" > "ID de cliente OAuth".
  3. Seleccione "Aplicación web"
  4. Anote el ID del cliente y el secreto del cliente
    - ID de cliente
    - Secreto del cliente
  5. Descargue el json secreto y cámbiele el nombre a credentials.json
- Generar una clave API
Vaya al motor de búsqueda personalizado y obtenga su ID

Instalación

Clon de Git

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

Configuración

Instalar el administrador de paquetes UV:

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

Crear y activar entorno virtual:

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

Instalar dependencias:

uv pip install -r requirements.txt

Obtener el token de actualización (si el token ha expirado, puede ejecutar esto)

uv run get_refresh_token.py

Esto hará lo siguiente:

Abra su navegador para la autenticación de Google OAuth
Solicitar los siguientes permisos:
- 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
Guarde las credenciales en token.json
Mostrar el token de actualización en la consola

Variables de entorno:

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

copiar credentials.json a la carpeta raíz del proyecto (py-mcp-google-toolbox)

Usando Docker

Construya la imagen de Docker:

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

Ejecute el contenedor:

docker run py-mcp-google-toolbox

Uso local

Ejecutar el servidor:

mcp dev server.py

Configurar los ajustes de MCP

Agregue la configuración del servidor a su archivo de configuración de MCP:

Aplicación de escritorio de Claude

Para instalar automáticamente a través de Smithery :

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

Para instalar manualmente, abra ~/Library/Application Support/Claude/claude_desktop_config.json

Agregue esto al objeto mcpServers :

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

IDE de cursor

abrir ~/.cursor/mcp.json

Agregue esto al objeto mcpServers :

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

para Docker

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

Documentación de herramientas

Herramientas de Gmail

list_emails : enumera los correos electrónicos recientes de la bandeja de entrada de Gmail con opciones de filtrado
search_emails : Realiza búsquedas avanzadas en Gmail con recuperación detallada del contenido del correo electrónico.
send_email : redacta y envía correos electrónicos con soporte para destinatarios CC y CCO
modify_email : Cambia los estados de los correos electrónicos (leídos/no leídos, archivados, eliminados) modificando las etiquetas

Herramientas de calendario

list_events : recupera los próximos eventos del calendario dentro de rangos de tiempo especificados
create_event : crea nuevos eventos de calendario con asistentes, ubicación y descripción
update_event : modifica eventos de calendario existentes con actualización de parámetros flexible
delete_event : elimina eventos del calendario por ID de evento

Herramientas de accionamiento

read_gdrive_file : lee y recupera contenido de archivos de Google Drive
search_gdrive : Busca archivos en Google Drive con consultas personalizables

Herramientas de búsqueda

search_google : Realiza búsquedas en Google y devuelve resultados formateados

Desarrollo

Para realizar pruebas locales, puede utilizar el script de cliente incluido:

# 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

Licencia

Licencia MIT

Google Toolbox