Gmail MCP Server

What is Gmail MCP Server?

Gmail MCP Server is a small, community-built Gmail MCP server written in Python that lets MCP clients such as Claude Desktop read your recent inbox and search your mail through the Gmail API, using OAuth2 with read-only access.

The project was created by GitHub user ajbr0wn (source: github.com/ajbr0wn/gmail-mcp-server). It is not made by Google. It exposes one resource and one tool, and it cannot send, delete or label messages. That makes it a narrow, low-risk choice when you only want an assistant to look things up in your mailbox.

How to use Gmail MCP Server?

The server runs locally over stdio. You need Python 3.12 (the README uses a conda environment), a Google Cloud project, and an OAuth client for the Gmail API. It is not published to PyPI, so you install it from a clone of the repository.

1. Create Google OAuth credentials

1. Create a project in the Google Cloud Console.
2. Enable the Gmail API.
3. Create OAuth 2.0 credentials with application type Desktop application.
4. Download the file and save it as credentials.json.

2. Install the server

git clone https://github.com/ajbr0wn/gmail-mcp-server.git
conda create -n mcp-gmail python=3.12
conda activate mcp-gmail
cd gmail-mcp-server
pip install -e .

3. Set the two required environment variables

• GMAIL_CREDENTIALS_FILE: path to your Google OAuth credentials file
• GMAIL_TOKEN_FILE: path where the authentication token will be saved (created automatically on first sign-in)

You can test the server directly before wiring it into a client:

GMAIL_CREDENTIALS_FILE="/path/to/credentials.json" \
GMAIL_TOKEN_FILE="/path/to/token.json" \
python -m gmail_mcp_server.server

Claude Desktop

Add this to claude_desktop_config.json, replacing every /path/to/ with your real paths:

{
  "mcpServers": {
    "gmail": {
      "command": "/path/to/conda/envs/mcp-gmail/bin/python",
      "args": ["-m", "gmail_mcp_server.server"],
      "env": {
        "PYTHONPATH": "/path/to/gmail-mcp-server/src",
        "GMAIL_CREDENTIALS_FILE": "/path/to/credentials.json",
        "GMAIL_TOKEN_FILE": "/path/to/token.json"
      }
    }
  }
}

Restart Claude Desktop. The first time Claude touches Gmail, a browser window opens so you can authorize the app; the token is then saved to GMAIL_TOKEN_FILE and refreshed automatically.

Claude Code

The README only documents Claude Desktop, but any stdio client can launch the same command with the same environment variables. In Claude Code:

claude mcp add gmail \
  -e PYTHONPATH=/path/to/gmail-mcp-server/src \
  -e GMAIL_CREDENTIALS_FILE=/path/to/credentials.json \
  -e GMAIL_TOKEN_FILE=/path/to/token.json \
  -- /path/to/conda/envs/mcp-gmail/bin/python -m gmail_mcp_server.server

For Cursor, VS Code and other clients, reuse the command, args and env values from the Claude Desktop block in that client's MCP config file.

Key features of Gmail MCP Server

• Reads the 10 most recent emails in your inbox through the gmail://inbox/recent resource.
• Searches mail with Gmail's standard search syntax (from:, after:, subject: and so on).
• Requests read-only Gmail access; no write permissions are asked for.
• OAuth2 sign-in in the browser on first use, with automatic token refresh afterwards.
• Credentials and tokens stay on your machine in files you choose.
• Detailed logging to stderr covering startup, authentication, resource and tool use, and errors.
• Small Python codebase that is easy to read and extend.

Gmail MCP Server tools

The server has a single tool plus one resource:

• search_emails takes a required query (any Gmail search string) and an optional max_results (default 10). Use it to find messages by sender, date range, subject or label.
• The gmail://inbox/recent resource is not a tool; clients that support MCP resources can attach it to give the model your 10 newest messages as context.

There are no tools for sending, drafting, archiving or deleting mail.

Use cases of Gmail MCP Server

• Quick inbox checks without leaving your assistant: "What are my latest emails about?"
• Finding a specific message: "Could you show me any emails from sanrio in the last two days?" (the README's own example)
• Pulling details out of receipts or confirmations: "Search for emails from my airline this month and list the booking references."
• Summarizing a thread of updates from one sender: "Find emails from GitHub about failed builds this week and summarize them."
• Feeding email context into a coding or writing task, for example looking up a customer's bug report before drafting a reply elsewhere.

Gmail MCP Server vs alternatives

• Google's Gmail MCP server: Google runs a remote Gmail MCP endpoint at https://gmailmcp.googleapis.com/mcp/v1 as part of the Google Workspace Developer Preview Program (setup guide). It uses Streamable HTTP and OAuth 2.0, and its tools include search_threads, get_thread, create_draft and label management. Pick it if you want a Google-hosted server that can also create drafts; pick this Gmail MCP server if you want a local, read-only setup with no preview enrollment.
• Fuller community servers: Other open-source Gmail MCP servers add sending, labels and attachments. Their scope is larger, so review the permissions they request before connecting a real mailbox.

Troubleshooting Gmail MCP Server

• ModuleNotFoundError: gmail_mcp_server: the client is using a different Python. Point command at the interpreter inside your mcp-gmail environment and set PYTHONPATH to the repo's src folder.
• Server fails at startup: check that both GMAIL_CREDENTIALS_FILE and GMAIL_TOKEN_FILE are set; the README marks both as required. Use full paths, not placeholders.
• No browser prompt or authorization errors: make sure the OAuth client type is Desktop application and the Gmail API is enabled in the same Google Cloud project as the credentials.
• Need to re-authorize or switch accounts: revoke access in your Google Account settings, delete the token file and run again to trigger a new sign-in.
• Unclear failures: read the server's stderr output; the server logs authentication status and errors there.