# š§ Gmail MCP Server
[](https://modelcontextprotocol.io)
[](https://www.python.org/)
An MCP server to integrate Gmail with Claude, Cursor, and other MCP clients.
Allows AI agents to read, search, draft, and send emails securely.
---
## š Quickstart
### 1. Remote Usage- **Recommended** ā
This method requires **no local python installation**.
Add this to your `mcp_config.json`:
```json
{
"mcpServers": {
"gmail-remote": {
"url": "https://gmail-mcp-server-fr3d.onrender.com/mcp",
"transport": "sse"
}
}
}
```
**How to use:**
1. Ask a question (e.g., "Check my email").
2. You will get a URL. Click to authorize Google.
3. Copy the code and paste it into the chat.
4. You are logged in!
---
### 2. Local Testing
If you prefer to run the server code locally on your machine.
#### 1. Install Dependencies
```bash
cd Gmail-mcp-server
pip install -r requirements.txt
```
#### 2. Get Google Credentials
1. Go to [Google Cloud Console](https://console.cloud.google.com/).
2. Create Project ā Enable **Gmail API**.
3. **Credentials** ā **Create OAuth Client ID** ā **Desktop App**.
4. Download JSON ā rename to `credentials.json` ā place in this folder.
#### 3. Authenticate (One-time)
```bash
python authenticate.py
```
This opens your browser for Google login and creates `token.json` automatically.
#### 4. Configure Editor
Add this to your `mcp_config.json`:
```json
{
"mcpServers": {
"gmail": {
"command": "python",
"args": ["<ABSOLUTE_PATH_TO_REPO>/server.py"]
}
}
}
```
*Note: Replace `<ABSOLUTE_PATH_TO_REPO>` with the actual full path to this directory.*
## š ļø Features
### Tools
| Tool | Description |
|------|-------------|
| `list_emails` | List/search emails (returns id, snippet, subject, from, date) |
| `read_email` | Read full email content by ID |
| `create_draft` | Create a draft email (requires `send_draft` to actually send) |
| `send_draft` | Send a drafted email |
### Prompts
| Prompt | Description |
|--------|-------------|
| `summarize_unread` | Summarize unread emails with priority |
| `draft_reply` | Draft reply to an email |
| `compose_email` | Compose new email |
| `search_emails` | Natural language email search |
| `daily_digest` | Daily email digest by category |
---
## š File Structure
```
gmail-mcp-server/
āāā server.py # Main MCP server (FastMCP)
āāā gmail_client.py # Gmail API wrapper library
āāā auth.py # OAuth2 & Auth logic
āāā credentials.json # Google App Credentials (YOU PROVIDE)
āāā token.json # User Access Token (GENERATED)
āāā requirements.txt # Python dependencies
```
---
## š Security
* **`credentials.json`**: Identifies the application. Low risk if shared, but keep private.
* **`token.json`**: **CRITICAL**. Contains acts-as-you keys. **NEVER SHARE**.
* **`.gitignore`**: Ensure both JSON files are ignored (default in this repo).
> **Note**: `send_draft` sends real emails. Use responsibly.
