Gmail MCP Server

# Gmail MCP Server Model Context Protocol (MCP) server for Gmail API integration. Provides 17 tools for email management, labels, threads, attachments, and drafts. ## Features ### Email Operations (7 tools) - **gmail_search_messages** - Search using Gmail query syntax (from:, to:, subject:, is:unread) - **gmail_get_message** - Get full message content with headers and body - **gmail_send_message** - Send email with to/cc/bcc recipients - **gmail_delete_message** - Permanently delete message (bypass trash) - **gmail_trash_message** - Move to trash (reversible) - **gmail_untrash_message** - Restore from trash - **gmail_modify_message_labels** - Add/remove labels from message ### Labels (3 tools) - **gmail_list_labels** - List all labels with IDs and types - **gmail_create_label** - Create new custom label - **gmail_delete_label** - Remove custom label ### Threads (3 tools) - **gmail_list_threads** - List conversation threads - **gmail_get_thread** - Get full thread with all messages - **gmail_modify_thread_labels** - Apply/remove labels from entire thread ### Attachments (1 tool) - **gmail_get_attachment** - Download attachment data ### Drafts (3 tools) - **gmail_list_drafts** - List draft messages - **gmail_create_draft** - Create new draft - **gmail_send_draft** - Send existing draft ## Installation ### 1. Install Dependencies ```bash cd ~/repos/3-resources/MCP/mcp-proxy/gmail-mcp uv venv source .venv/bin/activate uv pip install -r requirements.txt ``` ### 2. Google Cloud Console Setup 1. Go to [Google Cloud Console](https://console.cloud.google.com/) 2. Create a new project or select existing project 3. Enable the Gmail API: - Navigate to "APIs & Services" > "Library" - Search for "Gmail API" - Click "Enable" 4. Create OAuth 2.0 credentials: - Navigate to "APIs & Services" > "Credentials" - Click "Create Credentials" > "OAuth client ID" - Application type: "Desktop app" - Name: "Gmail MCP Server" - Click "Create" 5. Download credentials as `credentials.json` ### 3. Initial OAuth Flow Run the initial OAuth flow to obtain a refresh token: ```bash python3 oauth_setup.py ``` This will: - Open a browser for Google OAuth consent - Request gmail.modify scope - Save refresh token to display Copy the refresh token for the next step. ### 4. Store Credentials in OpenBao Store the OAuth credentials in OpenBao: ```bash # Ensure OpenBao agent is running start-openbao-mcp # Store credentials (replace values with your actual credentials) bao kv put secret/client0/prod-mcp-gmail-$(git config user.email | cut -d'@' -f1) \ client_id="YOUR_CLIENT_ID.apps.googleusercontent.com" \ client_secret="YOUR_CLIENT_SECRET" \ refresh_token="YOUR_REFRESH_TOKEN" ``` **Secret Path Pattern**: `secret/{client}/{env}-mcp-gmail-{username}` - Example: `secret/client0/prod-mcp-gmail-samuel` - Username is auto-detected from git config user.email ### 5. Test the Server ```bash # Test server startup python gmail_mcp.py # Should print "MCP_SERVER_READY" to stderr # Test with MCP Inspector (in separate terminal) npx @modelcontextprotocol/inspector python gmail_mcp.py ``` ### 6. Deploy to mcp-proxy Add to `~/.claude/mcp-proxy/config.json`: ```json { "mcpServers": { "gmail": { "command": "python", "args": ["/home/samuel/repos/3-resources/MCP/mcp-proxy/gmail-mcp/gmail_mcp.py"], "env": {} } } } ``` Then run structure_generator to create hierarchy files: ```bash cd ~/repos/3-resources/MCP/mcp-proxy ./structure_generator.py ``` ## Development Mode For local development without OpenBao: ```bash export OPENBAO_DEV_MODE=1 export GMAIL_CLIENT_ID="your-client-id" export GMAIL_CLIENT_SECRET="your-client-secret" export GMAIL_REFRESH_TOKEN="your-refresh-token" python gmail_mcp.py ``` ## OAuth Scopes This server requires the **gmail.modify** scope: - `https://www.googleapis.com/auth/gmail.modify` This provides full mailbox access including: - Read messages and threads - Send messages - Modify labels - Delete messages - Manage drafts ## Security - **Never commit credentials.json or tokens to git** - OAuth refresh tokens are stored securely in OpenBao - Access tokens are refreshed automatically on each request - All API communication uses HTTPS ## Troubleshooting ### "OPENBAO_ERROR: Agent not running" Start the OpenBao agent: ```bash export BW_SESSION=$(bw unlock --raw) start-openbao-mcp ``` ### "Failed to refresh OAuth token" The refresh token may be invalid or expired. Run `python oauth_setup.py` again to generate a new one. ### "Permission denied" errors Ensure the OAuth consent screen includes the gmail.modify scope. You may need to re-authorize. ### Rate Limiting Gmail API has these limits: - 1 billion quota units per day - 250 quota units per user per second - Batch requests: 100 requests per batch The server handles rate limit errors automatically with retry suggestions. ## Sources **Gmail API Documentation:** - [Gmail API Reference](https://developers.google.com/workspace/gmail/api/reference/rest) - [Python Quickstart](https://developers.google.com/workspace/gmail/api/quickstart/python) - [OAuth 2.0 for Google APIs](https://developers.google.com/identity/protocols/oauth2) **MCP Documentation:** - [Model Context Protocol](https://modelcontextprotocol.io) - [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)