README.md
A Gmail MCP server using OAuth2 bearer token auth via Dedalus
gmail-mcp
A Gmail MCP server using OAuth2 bearer token auth via the Dedalus MCP framework.
Tools
Messages
gmail_list_messages- List messages with search queriesgmail_get_message- Get a specific message by IDgmail_send_message- Send an emailgmail_trash_message- Move message to trashgmail_untrash_message- Remove message from trashgmail_modify_message- Add/remove labels on a message
Threads
gmail_list_threads- List email threads (conversations)gmail_get_thread- Get a thread with all messagesgmail_trash_thread- Move thread to trash
Labels
gmail_list_labels- List all labelsgmail_get_label- Get label detailsgmail_create_label- Create a new labelgmail_delete_label- Delete a user label
Drafts
gmail_list_drafts- List draft emailsgmail_get_draft- Get a draft by IDgmail_create_draft- Create a draftgmail_send_draft- Send a draftgmail_delete_draft- Delete a draft
Profile
gmail_get_profile- Get user's Gmail profile
Authentication
Gmail API requires OAuth2. The access token is provided at runtime via Dedalus credential exchange.
Required OAuth scopes (depending on operations):
https://www.googleapis.com/auth/gmail.readonly- Read-only accesshttps://www.googleapis.com/auth/gmail.send- Send emailshttps://www.googleapis.com/auth/gmail.modify- Modify messages/labelshttps://www.googleapis.com/auth/gmail.compose- Create drafts
Usage
Prerequisites
- A Dedalus API key (
dsk-live-*ordsk-test-*) - The
dedalus-labsPython SDK installed
Environment Variables
DEDALUS_API_KEY=dsk-live-your-key-here
DEDALUS_API_URL=https://api.dedaluslabs.ai
DEDALUS_AS_URL=https://as.dedaluslabs.ai
Example Client
See `src/_client.py` for a complete example client that handles the OAuth browser flow.
The first time you use the MCP server, you'll be prompted to authorize Gmail access via OAuth.
OAuth Flow
- On first request, you'll receive an
AuthenticationErrorwith aconnect_url - Open the URL in a browser to authorize Gmail access
- After authorization, retry the request - credentials are now stored
- Subsequent requests will work without re-authorization
Local Development
cd gmail-mcp
uv sync
uv run python src/main.py
API Reference
Tools (19)
gmail_list_messagesList messages with search queriesgmail_get_messageGet a specific message by IDgmail_send_messageSend an emailgmail_trash_messageMove message to trashgmail_untrash_messageRemove message from trashgmail_modify_messageAdd/remove labels on a messagegmail_list_threadsList email threads (conversations)gmail_get_threadGet a thread with all messagesgmail_trash_threadMove thread to trashgmail_list_labelsList all labelsgmail_get_labelGet label detailsgmail_create_labelCreate a new labelgmail_delete_labelDelete a user labelgmail_list_draftsList draft emailsgmail_get_draftGet a draft by IDgmail_create_draftCreate a draftgmail_send_draftSend a draftgmail_delete_draftDelete a draftgmail_get_profileGet user's Gmail profileEnvironment Variables
DEDALUS_API_KEYrequiredDedalus API key (dsk-live-* or dsk-test-*)DEDALUS_API_URLrequiredDedalus API endpoint URLDEDALUS_AS_URLrequiredDedalus AS endpoint URLConfiguration
claude_desktop_config.json
{"mcpServers":{"gmail":{"command":"uv","args":["run","--project","/path/to/gmail-mcp","src/main.py"],"env":{"DEDALUS_API_KEY":"dsk-live-your-key-here","DEDALUS_API_URL":"https://api.dedaluslabs.ai","DEDALUS_AS_URL":"https://as.dedaluslabs.ai"}}}}Try it
→Search my Gmail for messages from 'GitHub' about recent pull requests.
→Get the full conversation thread for the email with ID '12345'.
→Send an email to example@test.com with the subject 'Meeting Update' and a brief summary of our last call.
→List all my Gmail labels and create a new one called 'Project Alpha'.
→Find my latest draft and send it.