# MCP Google Hub FastMCP server for Google services (Gmail, Calendar, Drive) with **OMA Backend** integration for centralized OAuth 2.0 management. ## Features - =� **Dual Authentication Modes**: - **OMA Backend** (recommended): Server-to-server OAuth via centralized backend - **Local File** (legacy): Traditional file-based OAuth flow - =� **Gmail Tools**: Send, read, search, modify messages - =� **Calendar Tools**: View upcoming events, create events - =� **Drive Tools**: Search, create, update, delete, share files - =� **Auto Token Refresh**: Automatic OAuth token refresh handling ## Architecture ``` � � � � MCP Google Hub � > � OMA Backend � > � Google � � (This Project) � OAuth � (Auth Server) � OAuth � APIs � �� �� �� FastMCP Server Centralized OAuth Gmail, Calendar Token Management Drive, etc. ``` ### OMA Backend Integration **OMA** (OAuth Management & Authentication) Backend provides: - Centralized user authentication (JWT) - Google OAuth flow management - Secure encrypted token storage - Multi-user support - Automatic token refresh **📊 Detailed Documentation:** - [Architecture Diagrams (Mermaid)](docs/ARCHITECTURE_DIAGRAMS.md) - Visual flow diagrams - [Multi-User Architecture](docs/MULTI_USER_ARCHITECTURE.md) - Multi-user OAuth 2.0 details - [Docker Deployment Guide](docs/DOCKER_DEPLOYMENT.md) - **Production multi-user deployment** - [Integration Guide](docs/INTEGRATION.md) - Complete integration documentation - [Migration Summary](docs/MIGRATION_SUMMARY.md) - Changes and migration guide ## Installation ### Prerequisites - Python 3.12+ - OMA Backend server running (for `oma_backend` mode) - Google Cloud Project with OAuth credentials ### Setup 1. **Clone and install dependencies:** ```bash git clone cd mcpgoogle pip install -e . ``` 2. **Configure environment:** ```bash cp .env.example .env # Edit .env with your configuration ``` 3. **Choose authentication mode:** #### Option A: OMA Backend Mode (Recommended) ```env # .env AUTH_MODE=oma_backend OMA_BACKEND_URL=https://rndaibot.ru/api/v1 OMA_ACCESS_TOKEN=your_oma_access_token GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com GOOGLE_CLIENT_SECRET=your-client-secret ``` **How to get OMA_ACCESS_TOKEN:** 1. Navigate to OMA Backend web interface: `https://rndaibot.ru` 2. Register/Login with your account 3. Connect your Google account via the web UI 4. Copy your access token from the API response or browser cookies #### Option B: Local File Mode (Legacy) ```env # .env AUTH_MODE=local_file GOOGLE_CREDENTIALS_PATH=secrets/credentials.google.json GOOGLE_TOKEN_PATH=data/token.google.json ``` Download `credentials.json` from [Google Cloud Console](https://console.cloud.google.com/apis/credentials). ## Usage ### Running the Server ```bash # Start the MCP server python src/server.py # Or with FastMCP CLI fastmcp run src/server.py ``` Server will be available at: - **MCP Endpoint**: `http://localhost:8000/mcp/` - **Health Check**: `http://localhost:8000/health` ### Quick Test with curl ```bash # List available tools curl -X POST http://localhost:8000/mcp/ \ -H "Content-Type: application/json" \ -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' # Call a tool (list unread emails) curl -X POST http://localhost:8000/mcp/ \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "gmail_list_unread", "arguments": {"max_results": 5} } }' ``` ### OpenAI Agents Integration ```python from openai import OpenAI client = OpenAI(api_key="your-api-key") response = client.responses.create( model="gpt-4.1", tools=[{ "type": "mcp", "server_label": "mcpgoogle", "server_url": "http://localhost:8000/mcp/", "require_approval": "never" }], input="Check my unread emails and summarize them" ) print(response.output) ``` **See [MCP_GUIDE.md](docs/MCP_GUIDE.md) for complete integration examples and curl commands.** ## Authentication Flow (OMA Backend Mode) ``` 1. User logs in to OMA Backend web interface �> Receives JWT access_token 2. User connects Google account via web UI �> OMA Backend handles OAuth flow �> Stores encrypted Google credentials 3. MCP Google Hub requests credentials �> GET /api/v1/google/credentials �> Header: Authorization: Bearer {OMA_ACCESS_TOKEN} 4. OMA Backend returns Google OAuth tokens �> MCP Hub uses tokens to call Google APIs �> OMA Backend auto-refreshes expired tokens ``` ## Configuration Reference ### Environment Variables #### Google Authentication | Variable | Required | Default | Description | |----------|----------|---------|-------------| | `AUTH_MODE` | No | `oma_backend` | Authentication mode: `oma_backend` or `local_file` | | `OMA_BACKEND_URL` | Yes* | `https://rndaibot.ru/api/v1` | OMA Backend base URL | | `OMA_ACCESS_TOKEN` | Yes* | - | User's JWT token from OMA Backend | | `GOOGLE_CLIENT_ID` | Yes* | - | Google OAuth Client ID | | `GOOGLE_CLIENT_SECRET` | Yes* | - | Google OAuth Client Secret | | `OMA_VERIFY_SSL` | No | `true` | SSL verification (set `false` for dev) | | `GOOGLE_CREDENTIALS_PATH` | Yes** | `secrets/credentials.google.json` | Path to credentials file (local mode) | | `GOOGLE_TOKEN_PATH` | No | `data/token.google.json` | Path to token file (local mode) | | `GOOGLE_SCOPES` | No | See defaults | Space-separated Google API scopes | *Required for `AUTH_MODE=oma_backend` **Required for `AUTH_MODE=local_file` #### MCP Server Configuration | Variable | Required | Default | Description | |----------|----------|---------|-------------| | `MCP_AUTH_TOKEN` | No | - | Bearer token for MCP authentication (leave empty for dev) | | `MCP_CORS_ORIGINS` | No | `*` | Comma-separated allowed origins (use `*` for dev) | | `MCP_HOST` | No | `0.0.0.0` | Server bind address | | `MCP_PORT` | No | `8000` | Server port | | `MCP_TRANSPORT` | No | `streamable-http` | Transport: `streamable-http` or `http` | ### Default Google Scopes ```python [ "https://www.googleapis.com/auth/gmail.readonly", "https://www.googleapis.com/auth/gmail.modify", "https://www.googleapis.com/auth/gmail.send", "https://www.googleapis.com/auth/calendar", "https://www.googleapis.com/auth/calendar.events", "https://www.googleapis.com/auth/drive", ] ``` ## Project Structure ``` mcpgoogle/ � src/ � � __init__.py � � config.py # Configuration management � � core.py # FastMCP instance � � server.py # Main server entry point � � auth/ � � � __init__.py � � � google_auth.py # Multi-mode Google auth � � � oma_client.py # OMA Backend client � � tools/ � � __init__.py � � gmail_tool.py # Gmail MCP tools � � calendar_tool.py # Calendar MCP tools � � drive_tool.py # Drive MCP tools � tests/ � .env.example # Environment configuration template � pyproject.toml # Project dependencies � README.md # This file ``` ## API Reference ### Gmail Tools - `gmail_send_message(to, subject, body, cc=None, bcc=None)` - Send email - `gmail_list_unread(max_results=10)` - List unread messages - `gmail_search_messages(query, max_results=10)` - Search messages - `gmail_get_message(message_id)` - Get message details - `gmail_mark_as_read(message_id)` - Mark message as read - `gmail_modify_message(message_id, add_labels=[], remove_labels=[])` - Modify labels ### Calendar Tools - `calendar_upcoming(max_results=10, time_min=None)` - Get upcoming events ### Drive Tools - `drive_search(query, max_results=10)` - Search files - `drive_create_file(name, content, mime_type, folder_id=None)` - Create file - `drive_update_file(file_id, content)` - Update file content - `drive_delete_file(file_id)` - Delete file - `drive_share_file(file_id, email, role='reader')` - Share file - `drive_download_file(file_id)` - Download file content ## Security Best Practices ### OMA Backend Mode � **Recommended for production** - Centralized credential management - Encrypted token storage on backend - No local credential files - Multi-user support - Automatic token refresh - Audit logging (on OMA Backend) ### Local File Mode �� **Use only for development** - Credentials stored in local files - Manual OAuth flow required - Single-user only - Less secure for production ## MCP Endpoints The server exposes the following MCP endpoints: - **POST /mcp/** - Main MCP endpoint (JSON-RPC 2.0) - `tools/list` - List available tools with schemas - `tools/call` - Execute tool with arguments - **GET /health** - Health check endpoint ### Available Tools - `gmail_list_unread` - List unread emails - `gmail_search_messages` - Search emails by query - `gmail_get_message` - Get email content by ID - `gmail_send_message` - Send email with optional CC/BCC - `gmail_mark_as_read` - Mark email as read - `gmail_modify_message` - Modify email labels - `calendar_upcoming` - Get upcoming calendar events ## Troubleshooting ### MCP Server Issues **Server won't start:** ```bash # Install dependencies pip install -e . # Check configuration python -c "from src import config; config.validate_config()" ``` **401 Unauthorized (MCP endpoint):** - Disable auth: Set `MCP_AUTH_TOKEN=` in `.env` - Or include: `Authorization: Bearer your-token` header **CORS errors:** ```env # Allow all origins (dev) MCP_CORS_ORIGINS=* # Specific domains (prod) MCP_CORS_ORIGINS=https://api.openai.com,https://yourapp.com ``` ### Google OAuth Issues **Error: "OMA_ACCESS_TOKEN environment variable is required"** Set your OMA access token in `.env`: ```bash # Login to OMA Backend first curl -X POST https://rndaibot.ru/api/v1/auth/login \ -H "Content-Type: application/json" \ -d '{"username": "your_username", "password": "your_password"}' # Copy access_token from response to .env OMA_ACCESS_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... ``` **Error: "Google account not connected"** Connect Google account via OMA Backend web interface: 1. Navigate to `https://rndaibot.ru` 2. Login with your account 3. Go to Settings → Google Integration 4. Click "Connect Google Account" 5. Authorize Google OAuth flow **Error: "Invalid authentication scheme"** Ensure `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` match the credentials configured in OMA Backend. ## Development ### Running Tests ```bash pytest tests/ ``` ### Code Formatting ```bash ruff check src/ ruff format src/ ``` ## Documentation - **[MCP_GUIDE.md](docs/MCP_GUIDE.md)** - Complete OpenAI Agents integration guide with curl examples - **[ARCHITECTURE_DIAGRAMS.md](docs/ARCHITECTURE_DIAGRAMS.md)** - Visual flow diagrams - **[DOCKER_DEPLOYMENT.md](docs/DOCKER_DEPLOYMENT.md)** - Production deployment guide - **[INTEGRATION.md](docs/INTEGRATION.md)** - Complete integration documentation ## Related Projects - **OMA Backend**: OAuth Management & Authentication server - Repository: `oma-backend/` - API Docs: `https://rndaibot.ru/api/docs` - **Frontend**: Next.js web interface - Repository: `openai-realtime-agents/` - URL: `https://rndaibot.ru` ## External Resources - [MCP Specification](https://modelcontextprotocol.io/specification) - [FastMCP Documentation](https://gofastmcp.com/) - [OpenAI Agents SDK](https://openai.github.io/openai-agents-python/) ## License [Your License] ## Contributing [Contributing guidelines]