Which integrations are available for this server?

Provides read-only access to the Gmail API, enabling tools to retrieve user profiles, list labels, search and list messages using Gmail query operators, and fetch specific messages, threads, or attachments. Integrates with Google services via OAuth to provide secure, read-only access to user data within the Gmail ecosystem. Utilizes the Google Cloud Console for API management and OAuth client configuration to facilitate authorized access to Gmail data.

How do I use Gmail MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Gmail MCP find the latest invoice from Amazon in my inbox" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

GMAIL-MCP

A Dedalus MCP server for read-only access to the Gmail API v1.

Setup

1) Dedalus credentials (required)

This server uses the Dedalus MCP framework and expects your Dedalus credentials to be available as environment variables (for the MCP auth handshake).

2) Google Cloud setup (one-time)

Go to the Google Cloud Console
Create/select a project
Enable Gmail API
Configure OAuth consent screen
- If in testing mode: add your Google account as a Test user
Create OAuth client ID
- Application type: Desktop app
- Download the JSON (OAuth client credentials)

3) Configure environment

Copy .env.example to .env and set your OAuth client JSON path:

GOOGLE_OAUTH_CREDENTIALS=/absolute/path/to/your/oauth-client.json

4) Install dependencies

uv sync

5) Authenticate once (opens browser and stores tokens)

uv run python -m src.gmail_auth

Tokens will be stored at ~/.config/gmail-mcp/tokens.json by default.

6) Run the server

uv run python -m src.main

Available Tools (Read-only)

gmail_get_profile - Get Gmail profile
gmail_list_labels - List labels
gmail_list_messages - List/search messages (supports Gmail query operators)
gmail_get_message - Get a message by ID
gmail_get_thread - Get a thread by ID
gmail_get_attachment - Download an attachment by ID

Authentication

Google OAuth (recommended)

Set GOOGLE_OAUTH_CREDENTIALS
Run uv run python -m src.gmail_auth
gmail-mcp will auto-refresh access tokens when possible.

Default scope:

https://www.googleapis.com/auth/gmail.readonly

Environment variables

GOOGLE_OAUTH_CREDENTIALS: Path to downloaded OAuth client JSON (Desktop app)
GMAIL_TOKEN_PATH (optional): Token file location (default ~/.config/gmail-mcp/tokens.json)
GMAIL_SCOPES (optional): Comma-separated scopes (default is read-only)
GMAIL_ACCESS_TOKEN (optional/manual): If set, overrides all other auth logic