Google Services MCP Server 🚀

A comprehensive MCP (Model Context Protocol) server that provides secure access to Google services using OAuth authentication. Built with FastMCP and Google APIs, this server enables seamless integration with Gmail, Google Drive, Google Calendar, and user information.

✨ Features

• 🔐 Secure OAuth Authentication: Google OAuth 2.0 integration with FastMCP
• 📧 Gmail Integration: Search messages, retrieve labels, and access email data
• 💾 Google Drive Access: List and search files in Google Drive
• 📅 Calendar Management: Access calendar events and calendar information
• 👤 User Information: Get authenticated user profile data
• 🛡️ Production Ready: Environment-based configuration and error handling
• 🔄 Interactive Testing: Built-in test client with interactive mode

🏗️ Architecture

This MCP server uses the OAuth Proxy pattern to bridge Google's traditional OAuth with MCP's authentication requirements. It leverages FastMCP's GoogleProvider for seamless authentication handling.

Available Tools

Tool	Description	Parameters
get_user_info	Get authenticated user information	None
get_gmail_messages	Search and retrieve Gmail messages	query, max_results
get_gmail_labels	List all Gmail labels	None
get_drive_files	List and search Google Drive files	query, max_results
get_calendar_events	Get upcoming calendar events	calendar_id, days_ahead, max_results
get_calendars	List accessible calendars	None
server_health	Check server health and auth status	None

📋 Prerequisites

Before you begin, you will need:

1. Python 3.8+ installed on your system
2. Google Cloud Account with access to create OAuth 2.0 Client IDs
3. Google Cloud Project with the necessary APIs enabled

🚀 Quick Start

1. Clone and Setup

git clone <repository-url>
cd FastMcpGooglePython

# Install dependencies
pip install -r requirements.txt

# Or install in development mode
pip install -e .

2. Google Cloud Console Setup

Step 1: Create OAuth 2.0 Client ID

1. Go to the Google Cloud Console

2. Select your project or create a new one

3. Navigate to APIs & Services → OAuth consent screen

   • Choose "External" for testing or "Internal" for G Suite organizations
   • Fill in required information (app name, user support email, etc.)
   • Add your email to test users if using "External"

4. Navigate to APIs & Services → Credentials

5. Click "+ CREATE CREDENTIALS" → "OAuth client ID"

6. Configure your OAuth client:

   • Application type: Web application
   • Name: FastMCP Google Server (or your preferred name)
   • Authorized JavaScript origins: http://localhost:8000
   • Authorized redirect URIs: http://localhost:8000/auth/callback

7. Save your credentials:

   • Client ID: Ends with .apps.googleusercontent.com
   • Client Secret: Starts with GOCSPX-

Step 2: Enable Required APIs

Enable these APIs in your Google Cloud Project:

• Gmail API
• Google Drive API
• Google Calendar API
• Google+ API (for user info)

3. Environment Configuration

Create a .env file from the example:

cp .env.example .env

Edit .env with your Google OAuth credentials:

# Required: Your Google OAuth credentials
FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_SECRET=GOCSPX-your-client-secret

# Server configuration
FASTMCP_SERVER_AUTH_GOOGLE_BASE_URL=http://localhost:8000
FASTMCP_SERVER_AUTH_GOOGLE_REDIRECT_PATH=/auth/callback

# Scopes (comma-separated)
FASTMCP_SERVER_AUTH_GOOGLE_REQUIRED_SCOPES=openid,https://www.googleapis.com/auth/userinfo.email,https://www.googleapis.com/auth/userinfo.profile,https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/drive.readonly,https://www.googleapis.com/auth/calendar.readonly

4. Run the Server

cd src
python server.py

You should see:

🚀 Starting Google Services MCP Server...
📱 Server will be available at: http://localhost:8000
🔐 OAuth callback URL: http://localhost:8000/auth/callback

📋 Available tools:
   - get_user_info: Get authenticated user information
   - get_gmail_messages: Search and retrieve Gmail messages
   - get_gmail_labels: List Gmail labels
   - get_drive_files: List Google Drive files
   - get_calendar_events: Get upcoming calendar events
   - get_calendars: List accessible calendars
   - server_health: Check server status

5. Test the Connection

In a new terminal, run the test client:

cd src
python test_client.py

Or for interactive testing:

python test_client.py --interactive

📖 Usage Examples

Basic Client Connection

from fastmcp import Client
import asyncio

async def main():
    async with Client("http://localhost:8000/mcp/", auth="oauth") as client:
        # Get user information
        user_info = await client.call_tool("get_user_info")
        print(f"Hello, {user_info['name']}!")
        
        # Search Gmail
        messages = await client.call_tool("get_gmail_messages", {
            "query": "from:important@example.com",
            "max_results": 5
        })
        
        # List Drive files
        files = await client.call_tool("get_drive_files", {
            "query": "name contains 'report'",
            "max_results": 10
        })
        
        # Get calendar events
        events = await client.call_tool("get_calendar_events", {
            "days_ahead": 7,
            "max_results": 10
        })

asyncio.run(main())

Gmail Search Examples

# Search for unread emails
messages = await client.call_tool("get_gmail_messages", {
    "query": "is:unread",
    "max_results": 20
})

# Search by sender
messages = await client.call_tool("get_gmail_messages", {
    "query": "from:boss@company.com",
    "max_results": 10
})

# Search by subject
messages = await client.call_tool("get_gmail_messages", {
    "query": "subject:meeting",
    "max_results": 15
})

Drive Search Examples

# Search for PDFs
files = await client.call_tool("get_drive_files", {
    "query": "mimeType='application/pdf'",
    "max_results": 20
})

# Search by name
files = await client.call_tool("get_drive_files", {
    "query": "name contains 'budget'",
    "max_results": 10
})

# Search for shared files
files = await client.call_tool("get_drive_files", {
    "query": "sharedWithMe=true",
    "max_results": 15
})

🔧 Configuration Options

Environment Variables

Variable	Default	Description
FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_ID	Required	Google OAuth Client ID
FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_SECRET	Required	Google OAuth Client Secret
FASTMCP_SERVER_AUTH_GOOGLE_BASE_URL	http://localhost:8000	Server base URL for OAuth
FASTMCP_SERVER_AUTH_GOOGLE_REDIRECT_PATH	/auth/callback	OAuth redirect path
FASTMCP_SERVER_AUTH_GOOGLE_TIMEOUT_SECONDS	30	API request timeout
DEBUG	false	Enable debug mode
LOG_LEVEL	INFO	Logging level

Google API Scopes

The server requests these permissions by default:

• openid: Basic OpenID Connect
• userinfo.email: User email address
• userinfo.profile: User profile information
• gmail.readonly: Read-only Gmail access
• drive.readonly: Read-only Drive access
• calendar.readonly: Read-only Calendar access

🧪 Development

Project Structure

FastMcpGooglePython/
├── src/
│   ├── server.py          # Main MCP server
│   ├── test_client.py     # Test client
│   └── config.py          # Configuration management
├── tests/                 # Unit tests
├── requirements.txt       # Dependencies
├── pyproject.toml        # Project metadata
├── .env.example          # Environment template
└── README.md            # This file

Running Tests

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/

# Run with coverage
pytest tests/ --cov=src/

Code Style

This project follows Python best practices:

• PEP 8 style guide
• Type hints for better code documentation
• Async/await for optimal performance
• Error handling with proper exception management

🐛 Troubleshooting

Common Issues

1. "OAuth credentials not found" error

• Ensure .env file exists with correct Google OAuth credentials
• Verify environment variable names match exactly

2. "Connection failed" when running test client

• Make sure the server is running: python src/server.py
• Check that port 8000 is not in use by another application
• Verify server URL is http://localhost:8000

3. Google OAuth redirect errors

• Ensure redirect URI in Google Cloud Console matches exactly: http://localhost:8000/auth/callback
• Check that the base URL in .env is correct
• For production, use HTTPS URLs

4. "Insufficient permissions" for Google APIs

• Verify required APIs are enabled in Google Cloud Console
• Check that OAuth consent screen is properly configured
• Ensure your Google account has necessary permissions

5. SSL/HTTPS issues in production

• Update FASTMCP_SERVER_AUTH_GOOGLE_BASE_URL to use HTTPS
• Ensure SSL certificate is properly configured
• Update Google OAuth redirect URIs to use HTTPS

Debug Mode

Enable debug mode for detailed logging:

DEBUG=true python src/server.py

Logs and Monitoring

Check the server logs for detailed error information:

# Server logs show authentication flow and API calls
python src/server.py

# Client logs show connection and tool execution details  
python src/test_client.py

📚 API Reference

Server Tools

get_user_info()

Returns authenticated user information from Google.

Returns:

{
    "google_id": "user-id",
    "email": "user@example.com", 
    "name": "User Name",
    "given_name": "User",
    "family_name": "Name",
    "picture": "https://...",
    "locale": "en",
    "verified_email": true
}

get_gmail_messages(query="", max_results=10)

Search and retrieve Gmail messages.

Parameters:

• query (str): Gmail search query
• max_results (int): Maximum messages to return (1-100)

Returns:

{
    "messages": [
        {
            "id": "message-id",
            "thread_id": "thread-id",
            "from": "sender@example.com",
            "to": "recipient@example.com", 
            "subject": "Subject line",
            "date": "Wed, 1 Jan 2024 12:00:00 +0000",
            "snippet": "Message preview..."
        }
    ],
    "total_found": 10,
    "query": "search query"
}

get_drive_files(query="", max_results=10)

List and search Google Drive files.

Parameters:

• query (str): Drive search query
• max_results (int): Maximum files to return (1-100)

Returns:

{
    "files": [
        {
            "id": "file-id",
            "name": "document.pdf",
            "mime_type": "application/pdf",
            "size": 1024000,
            "created_time": "2024-01-01T12:00:00.000Z",
            "modified_time": "2024-01-02T12:00:00.000Z",
            "owners": ["owner@example.com"],
            "shared": false
        }
    ],
    "total_found": 5,
    "query": "search query"
}

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes and add tests
4. Run tests: pytest
5. Commit changes: git commit -am 'Add feature'
6. Push to branch: git push origin feature-name
7. Create a Pull Request

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

🙏 Acknowledgments

• FastMCP - The framework that makes this integration possible
• Google APIs - For comprehensive API access
• Model Context Protocol - For the MCP standard

---

Need help? Open an issue on GitHub or check the FastMCP documentation.