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