gmail-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| GMAIL_MCP_CREDENTIALS | No | Path to the Google OAuth Desktop app credentials JSON. Defaults to ~/.gmail-mcp/credentials.json. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Multiple Gmail accounts may be connected. Call list_accounts first. account may be an email, a unique alias, or a group name (e.g. 'work') shared by several accounts. search_emails accepts a group or no account to search several inboxes at once; every result row says which account it came from. All other tools need exactly one account (email or alias): use the account value from the search result row. If only one account exists it is used implicitly. Sending tools (send_email, reply_to_email, forward_email, send_draft) are two-step: the first call returns a preview and a confirm_token and sends nothing. Show the preview to the user and, only after they approve, call the same tool again with identical arguments plus confirm_token. Tokens are single use and expire after 5 minutes; prefer create_draft when unsure.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| list_accountsA | List connected Gmail accounts (email, alias, group). |
| add_accountB | Connect a new Gmail account. Opens a browser window on the machine running this server
and waits up to 3 minutes for sign-in. Prefer the CLI: |
| assign_accountA | Assign an account to a group such as 'work' or 'personal' (None clears it). Many accounts may share a group. |
| remove_accountA | Disconnect a Gmail account (email or alias): revokes and deletes its stored token. Two-step: first call returns a confirm_token; call again with it to remove. |
| search_emailsA | Search messages using Gmail search syntax (e.g. 'from:bob is:unread'). |
| get_threadA | Read all messages in a thread (headers, plain-text body, attachment names). |
| list_draftsC | List drafts with subject and recipients. |
| create_draftB | Create a draft (does not send). |
| create_reply_draftB | Create a threaded reply draft to a message (does not send). |
| send_emailB | Send a new email. Two-step: first call returns a preview + confirm_token; call again with it to send.
|
| reply_to_emailB | Reply in-thread to a message. Two-step: first call returns a preview + confirm_token; call again with it
to send. |
| forward_emailA | Forward a message with its attachments. Two-step: first call returns a preview + confirm_token; call again
with it to send. |
| send_draftA | Send an existing draft. Two-step: first call returns a preview + confirm_token; call again with it to send.
|
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 13 tools
Each tool maps to a distinct resource/action, and the account-scoped vs. mail-scoped tools are clearly separated. The only mild overlap is create_draft vs. create_reply_draft, but the descriptions make the threaded-reply distinction explicit.
All 13 tools follow a strict snake_case verb_noun pattern (list_accounts, add_account, search_emails, create_draft, send_email, forward_email). Action verbs are chosen consistently from a small, predictable vocabulary.
13 tools is well within the ideal range and each one covers a real workflow step (account management, search/read, drafts, sending). Nothing appears redundant or padded.
Read and send coverage is strong, but there are notable gaps: no delete/update draft, no way to trash, archive, label, or mark messages read/unread, and attachments are only listed by name with no download. These omissions will block common inbox-management workflows.