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

Go to the Google Cloud Console
Create a new project (or select an existing one)
Enable the following APIs:
- Gmail API — Enable
- Google Calendar API — Enable
- Google Drive API — Enable
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
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