# Google MCP Server

A locally-hosted [MCP](https://modelcontextprotocol.io) server built with [FastMCP 3.x](https://gofastmcp.com) 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

```bash
# 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](https://console.cloud.google.com/)
2. Create a new project (or select an existing one)
3. Enable the following APIs:
   - **Gmail API** — [Enable](https://console.cloud.google.com/apis/library/gmail.googleapis.com)
   - **Google Calendar API** — [Enable](https://console.cloud.google.com/apis/library/calendar-json.googleapis.com)
   - **Google Drive API** — [Enable](https://console.cloud.google.com/apis/library/drive.googleapis.com)
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:

```bash
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)

```bash
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)

```bash
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`):

```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):

```json
{
  "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
```