gmail-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| PIGEON_MCP_HTTP_HOST | No | HTTP bind address | 127.0.0.1 |
| PIGEON_MCP_HTTP_PORT | No | HTTP port | 8879 |
| PIGEON_MCP_LOG_LEVEL | No | Server log level | |
| PIGEON_MCP_TOKENS_DIR | No | OAuth token storage directory | ~/.config/pigeon-mcp/tokens |
| PIGEON_MCP_ENVIRONMENT | No | Label for logs/status | |
| PIGEON_MCP_OUTBOX_ROOT | No | Send/stage attachment paths | ~/Outbox |
| PIGEON_MCP_DOWNLOAD_ROOT | No | get_attachment writes | ~/Inbox |
| PIGEON_MCP_GOOGLE_CLIENT_ID | No | Optional, stdio only: Desktop client id | |
| PIGEON_MCP_HTTP_BEARER_TOKEN | Yes | Bearer token for HTTP transport | |
| PIGEON_MCP_OAUTH_REDIRECT_URI | No | Optional, stdio only: loopback callback for a Desktop client | |
| PIGEON_MCP_GOOGLE_CLIENT_SECRET | No | Optional, stdio only: Desktop client secret | |
| PIGEON_MCP_GOOGLE_WEB_CLIENT_ID | Yes | Google Web OAuth client id | |
| PIGEON_MCP_GOOGLE_WEB_CLIENT_SECRET | Yes | Google Web OAuth client secret | |
| PIGEON_MCP_OAUTH_PUBLIC_REDIRECT_URI | Yes | Public HTTPS callback — must match the Web client exactly |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
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 |
|---|---|
| gmail_statusA | Report server version and configuration (no Gmail API calls). |
| accounts_listA | List connected Gmail addresses and whether each refresh token still works. |
| accounts_auth_startA | Start Google OAuth for a mailbox over HTTP. Returns auth_url for a human to open; consent completes via the public /oauth/callback and the account appears in accounts_list. |
| identities_listA | Verified send-as identities for an account. Only these may be used as from_identity. |
| accounts_addA | Connect a Gmail account via local loopback OAuth (stdio only). |
| accounts_removeA | Remove a connected Gmail account and revoke its token at Google. |
| sendB | Send new mail. Attachments are outbox file paths only. Returns proof payload. from_identity: optional verified send-as address (see identities_list). Sets From with its display name and Reply-To. Empty = the account address itself. |
| replyC | Reply on a thread. Same attachment and proof rules as send. |
| forwardC | Forward a message on-thread. Same attachment and proof rules as send. |
| searchC | Search Gmail threads using Gmail query syntax. |
| messages_listA | List messages (not threads) with headers only — no bodies. Use for routing sweeps: originalTo is the real recipient behind a catch-all; authResults carries dkim/dmarc. Fetch bodies afterwards with get_message only where needed. |
| get_threadB | Get messages on a thread. format=metadata is headers+snippet only (cheap); plain adds the text body; full adds HTML and attachment metadata. |
| get_messageA | Get one message. format=metadata is headers+snippet only (cheap); plain adds the text body; full adds HTML and attachment metadata. |
| get_attachmentA | Write an attachment under download_root. output_path may be a bare filename (lands in download_root) or an absolute path under it. Returns path and size. |
| labels_listA | List system and user labels for an account. |
| labels_createC | Create a user label. |
| labelA | Add labels to a thread (comma-separated names or ids). |
| unlabelA | Remove labels from a thread (comma-separated names or ids). |
| archiveB | Remove INBOX from a thread. |
| trashC | Move a thread to trash. |
| untrashB | Restore a thread from trash. |
| draft_createC | Create a draft with the same MIME rules as send (from_identity as in send). |
| draft_sendB | Send a draft with post-send proof. |
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 23 tools
Most tools target clearly distinct actions or resources, such as send vs reply vs forward or get_thread vs get_message. A few boundaries are close, notably accounts_add vs accounts_auth_start and get_message vs get_thread, but the descriptions are sufficient to avoid serious misselection.
The naming style is mixed: some tools use resource_action (accounts_list, labels_create), some use action_resource (get_attachment, get_thread), and some are bare verbs (send, reply, archive, label). Within subfamilies the naming is consistent, but across the whole set there is no single predictable pattern.
23 tools is on the heavy side and falls into the borderline range for a single server. However, the count is justified by the breadth of Gmail functionality covered: accounts, labels, threads, messages, drafts, sending, and attachments.
The tool surface covers core Gmail workflows well: search, read, send, reply, forward, draft, label, archive, trash, and attachment retrieval. Minor gaps exist, such as no explicit mark-read/unread or message mutation beyond labels and trash, but agents can work around these.