Google MCP Server

A locally-hosted MCP server built with FastMCP 3.x that connects to your personal Google account and exposes Gmail, Google Calendar, and Google Drive as tools.

Available Tools

Service	Tool	Description
Gmail	list_emails	List recent emails from a label
Gmail	read_email	Read full content of an email
Gmail	send_email	Send a new email
Gmail	search_emails	Search emails with Gmail query syntax
Calendar	list_calendars	List all accessible calendars
Calendar	list_events	List upcoming events
Calendar	create_event	Create a new calendar event
Drive	list_files	List files (optionally in a folder)
Drive	read_file	Read text content of a file
Drive	search_files	Search for files by name or query

Prerequisites

• Python 3.10+
• A Google account
• A Google Cloud project with OAuth 2.0 credentials

Setup

1. Install dependencies

# Using pip
pip install -e .

# Or using uv
uv pip install -e .

2. Set up Google Cloud credentials

1. Go to the Google Cloud Console
2. Create a new project (or select an existing one)
3. Enable the following APIs:
   • Gmail API — Enable
   • Google Calendar API — Enable
   • Google Drive API — Enable
4. Configure the OAuth consent screen:
   • Go to APIs & Services → OAuth consent screen
   • Choose External user type
   • Fill in the required fields (app name, support email)
   • Add your email address as a test user
5. Create OAuth 2.0 credentials:
   • Go to APIs & Services → Credentials
   • Click + CREATE CREDENTIALS → OAuth client ID
   • Application type: Desktop app
   • Download the JSON file and save it as credentials.json in the project root

3. (Optional) Configure environment

Copy the example env file and adjust paths if needed:

cp .env.example .env

The defaults (credentials.json and token.json in the project root) work for most setups.

Running the Server

stdio transport (for Cursor / Claude Desktop)

python server.py

On first run, a browser window will open asking you to sign in with your Google account and grant permissions. The token is cached in token.json for subsequent runs.

HTTP transport (for remote/browser clients)

fastmcp run server.py:mcp --transport http --port 8000

The server will be available at http://localhost:8000/mcp.

Connecting to Cursor

Add this to your Cursor MCP settings (.cursor/mcp.json):

{
  "mcpServers": {
    "google": {
      "command": "python",
      "args": ["server.py"],
      "cwd": "/path/to/mcp-playground"
    }
  }
}

Connecting to Claude Desktop

Add this to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "google": {
      "command": "python",
      "args": ["/path/to/mcp-playground/server.py"]
    }
  }
}

Google API Scopes

This server requests the following OAuth scopes (narrowly scoped for safety):

Scope	Access
gmail.readonly	Read-only access to Gmail
gmail.send	Send emails only
calendar.events	Read and write calendar events
drive.readonly	Read-only access to Drive files

If you change scopes in auth/google_auth.py, delete token.json and re-authenticate.

Project Structure

mcp-playground/
├── server.py              # FastMCP server entry point
├── auth/
│   └── google_auth.py     # OAuth2 flow + service builders
├── tools/
│   ├── gmail.py           # Gmail tools
│   ├── calendar.py        # Calendar tools
│   └── drive.py           # Drive tools
├── pyproject.toml         # Dependencies
├── .env.example           # Environment config template
└── README.md