gmail-mcp-server by Hlake7 - MCP Server

Gmail MCP Server Setup Guide

This guide will help you set up your own Gmail MCP (Model Context Protocol) server to allow Claude to access and manage your Gmail account.

What This Does

This MCP server gives Claude the ability to:

List and search your emails
Read email content and details
Send new emails
Manage Gmail labels (add, remove, create)
Mark emails as read/unread
Delete emails
List all available labels

Prerequisites

Node.js (v16 or higher)
A Google account with Gmail
Claude Desktop app or MCP-compatible client

Setup Instructions

1. Clone and Setup the Project

# Clone or copy the gmail-mcp-server folder
cd path/to/your/projects
git clone https://github.com/yourusername/gmail-mcp-server.git
cd gmail-mcp-server
npm install

2. Google Cloud Console Setup

Go to the Google Cloud Console
Create a new project or select an existing one
Enable the Gmail API:
- Go to "APIs & Services" > "Library"
- Search for "Gmail API"
- Click on it and press "Enable"

3. Create OAuth 2.0 Credentials

Go to "APIs & Services" > "Credentials"
Click "Create Credentials" > "OAuth 2.0 Client IDs"
If prompted, configure the OAuth consent screen first:
- Choose "External" user type
- Fill in required fields (App name, User support email, Developer contact)
- Add your email to test users
For the OAuth 2.0 Client ID:
- Application type: "Desktop application"
- Name: "Gmail MCP Server" (or whatever you prefer)
Download the JSON file and save it as credentials.json in your project root

4. Configure the MCP Server

Copy the example environment file:
```
cp .env.example .env
```

Update .env with your settings (optional):

GMAIL_CREDENTIALS_PATH=./credentials.json
GMAIL_TOKEN_PATH=./token.json
PORT=3000

5. First-Time Authentication

Run the server for the first time:
```
npm start
```
The server will open a browser window for Google OAuth
Sign in with your Google account
Grant the requested permissions
The server will save your authentication token automatically

6. Configure Claude Desktop

Add the MCP server to your Claude Desktop configuration:

On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json On Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["C:\\full\\path\\to\\your\\gmail-mcp-server\\server.js"],
      "cwd": "C:\\full\\path\\to\\your\\gmail-mcp-server",
      "env": {
        "GMAIL_CREDENTIALS_PATH": "C:\\full\\path\\to\\your\\gmail-mcp-server\\credentials.json"
      }
    }
  }
}

Windows Example:

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["C:\\Users\\YourName\\Projects\\gmail-mcp-server\\server.js"],
      "cwd": "C:\\Users\\YourName\\Projects\\gmail-mcp-server",
      "env": {
        "GMAIL_CREDENTIALS_PATH": "C:\\Users\\YourName\\Projects\\gmail-mcp-server\\credentials.json"
      }
    }
  }
}

7. Restart Claude Desktop

Close and reopen Claude Desktop. You should now see Gmail tools available in your conversations.

Testing the Setup

Try asking Claude:

"List my recent emails"
"Show me unread emails"
"Send an email to [someone]"

File Structure

gmail-mcp-server/
├── server.js            # Main server file
├── package.json         # Dependencies
├── credentials.json     # Google OAuth credentials (you create this)
├── token.json          # OAuth token (auto-generated)
├── .env                # Environment variables (optional)
├── .env.example        # Environment template
├── .gitignore          # Git ignore file
└── README.md           # This file

Security Notes

Never commit credentials.json or token.json to version control
The .gitignore file is configured to exclude these sensitive files
Keep your OAuth credentials secure and don't share them
Consider using a dedicated Google account for testing

Troubleshooting

Authentication Issues

Make sure the Gmail API is enabled in Google Cloud Console
Check that your OAuth consent screen is properly configured
Verify the credentials.json file is in the correct location

Permission Errors

Ensure your Google account has the necessary permissions
Try re-running the authentication flow by deleting token.json

Claude Integration Issues

Verify the path in claude_desktop_config.json is correct
Make sure Claude Desktop is fully restarted after configuration changes
Check that Node.js is in your system PATH

Available Gmail Scopes

The server requests these Gmail permissions:

https://www.googleapis.com/auth/gmail.readonly - Read emails
https://www.googleapis.com/auth/gmail.send - Send emails
https://www.googleapis.com/auth/gmail.modify - Modify emails (labels, read status)

Support

If you run into issues:

Check the console output for error messages
Verify all setup steps were completed
Make sure all dependencies are installed
Try deleting token.json and re-authenticating

Contributing

Feel free to submit issues, fork the repository, and create pull requests for any improvements.

License

This project is licensed under the ISC License.