# Gmail MCP Server
This MCP (Model Context Protocol) server provides tools for common operations with gmail.
## Features
- `send_mail`: Send new emails
## Prerequisites
1. **Python 3.12+**
2. [**uv**](https://github.com/astral-sh/uv) - Fast Python package installer and resolver
3. **Google Cloud Console Setup**
- Go to: [Google Cloud Console](https://console.cloud.google.com/)
- Create a new project for this MCP Server
- Enable Gmail API
- Go to: **APIs and services > Library**
- Search: **Gmail API**
- Click on: **Gmail API** tile in the results
- Click on: **Enable**
- Setup OAuth
- Go to: **APIs and services > Credentials**
- Click on": **Create Credentials > OAuth client ID**
- Choose Application Type: **Web application**
- Add: **Authorised redirect URIs**: **http://localhost:4321/**
- Create client
- Download the JSON and save it to `credentials.json` in this project root. This has the **Client ID**, **Client Secret**, etc.
## Installation
1. Clone this repository:
```bash
git clone https://github.com/heuristech/gmail-mcp-server.git
cd gmail-mcp-server
```
2. Create a virtual environment and install the package in development mode:
```bash
# Create a virtual environment
uv venv
# Activate the virtual environment
# On macOS/Linux:
source .venv/bin/activate
# On Windows:
.venv\Scripts\activate
# Install dependencies
uv sync
```
**Get Refresh Token**
```python
python get_refresh_token.py
```
This will:
1. Start a server on `port`: `4321` to receive `tokens` post Google OAuth
2. Open your browser for Google OAuth
3. On succeeful authentication it will save `token.json` with `refresh_token` along with `client_id`, and `client_secret`.
4. It will also display the `refresh_token` on console.
**Create .env**
```bash
copy example.env .env
```
Setup the corresponding value using what you received in the previous step.
## Inspect
Use MCP Inspector to test it in the development mode.
```bash
mcp dev server.py
```
## Claude Desktop Integration
Once your server is ready, install it in Claude Desktop
```bash
mcp install server.py --with google-auth --with google-auth-oauthlib --with google-auth-httplib2 --with google-api-python-client -f .env
```
MCP server configuration:
```json
{
"mcpServers": {
"gmail-mcp-server": {
"command": "uv",
"args": [
"--directory",
"/:your.path.to/gmail-mcp-server/server.py",
"run",
"server.py"
],
"env": {
"CLIENT_ID": "google.auth.app.client.id",
"CLIENT_SECRET": "google.auth.app.client.secret",
"REFRESH_TOKEN": "google.auth.app.refresh.token"
}
}
}
}
```
