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:
- 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.jsonin 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