sudo-mcp-gmail

A Python MCP server for Gmail that lets MCP clients such as Claude Desktop, Codex desktop, and other compatible clients use the published package name sudo-mcp-gmail:

• create Gmail drafts with to, cc, bcc, subject, body_text, optional body_html, and attachments from local files or HTTPS URLs
• update existing Gmail drafts
• fetch and send Gmail drafts by draft ID
• reply, reply-all, and forward messages
• send Gmail messages with the same fields and attachment support
• list Gmail labels
• mark messages read or unread
• list recent Gmail messages
• read a specific Gmail message
• search Gmail using raw Gmail queries or structured filters such as subject keywords, body keywords, senders, and company domains
• preserve original attachment filenames and file extensions when safely available

Warning: send_gmail_message, send_gmail_draft, reply_to_gmail_message, reply_all_gmail_message, and forward_gmail_message send mail immediately from your Gmail account.

Tools

create_gmail_draft

Creates a Gmail draft with optional attachments.

Inputs:

• to: list[str]
• subject: str
• body_text: str
• cc: list[str] | None
• bcc: list[str] | None
• body_html: str | None
• attachments: list[str] | None — local file paths or HTTPS URLs

update_gmail_draft

Updates an existing draft by Gmail draft ID.

Inputs:

• draft_id: str
• to: list[str]
• subject: str
• body_text: str
• cc: list[str] | None
• bcc: list[str] | None
• body_html: str | None
• attachments: list[str] | None — local file paths or HTTPS URLs

get_gmail_draft

Fetches a draft by Gmail draft ID.

Inputs:

• draft_id: str

send_gmail_draft

Sends an existing draft by Gmail draft ID.

Inputs:

• draft_id: str

reply_to_gmail_message

Replies to a Gmail message.

Inputs:

• message_id: str
• body_text: str
• body_html: str | None
• attachments: list[str] | None — local file paths or HTTPS URLs

reply_all_gmail_message

Replies-all to a Gmail message.

Inputs:

• message_id: str
• body_text: str
• body_html: str | None
• attachments: list[str] | None — local file paths or HTTPS URLs

forward_gmail_message

Forwards a Gmail message.

Inputs:

• message_id: str
• to: list[str]
• body_text: str
• cc: list[str] | None
• bcc: list[str] | None
• body_html: str | None
• attachments: list[str] | None — local file paths or HTTPS URLs

send_gmail_message

Sends a Gmail message immediately.

Inputs:

• to: list[str]
• subject: str
• body_text: str
• cc: list[str] | None
• bcc: list[str] | None
• body_html: str | None
• attachments: list[str] | None — local file paths or HTTPS URLs

list_gmail_labels

Lists Gmail labels.

mark_gmail_message_read

Marks a Gmail message as read.

Inputs:

• message_id: str

mark_gmail_message_unread

Marks a Gmail message as unread.

Inputs:

• message_id: str

list_gmail_messages

Lists Gmail messages.

Inputs:

• query: str | None
• label_ids: list[str] | None
• max_results: int

get_gmail_message

Fetches a full Gmail message.

Inputs:

• message_id: str

search_gmail_messages

Searches Gmail using structured filters and returns the Gmail query it built.

Inputs:

• raw_query: str | None
• subject_keywords: list[str] | None
• body_keywords: list[str] | None
• from_addresses: list[str] | None
• company_domains: list[str] | None
• has_attachments: bool | None
• newer_than_days: int | None
• label_ids: list[str] | None
• max_results: int

Prerequisites

• Python 3.10+
• A Google account with Gmail enabled
• A Google Cloud project with the Gmail API enabled
• OAuth desktop client credentials downloaded as JSON

Gmail API setup

1. Open Google Cloud Console.
2. Create or select a project.
3. Enable Gmail API.
4. Go to APIs & Services → OAuth consent screen.
5. Configure the consent screen.
6. Go to APIs & Services → Credentials.
7. Create OAuth client ID credentials.
8. Choose Desktop app.
9. Download the JSON credentials file.
10. Save it as credentials.json in the project root, or set a custom path with GMAIL_MCP_CREDENTIALS_FILE.

Install from source

python -m venv .venv
source .venv/Scripts/activate
pip install -e .

Install from pip

After you publish the package to PyPI, install it anywhere without cloning the repo:

pip install sudo-mcp-gmail

Then run it with:

sudo-mcp-gmail

If you want to pin a specific release:

pip install sudo-mcp-gmail==0.1.0

Authentication

The first time the server needs Gmail access, it opens a local browser OAuth flow.

By default:

• client credentials file: credentials.json
• refresh token file: token.json

Environment variables:

• GMAIL_MCP_CREDENTIALS_FILE — path to Google OAuth desktop credentials JSON
• GMAIL_MCP_TOKEN_FILE — path where the Gmail refresh token will be stored

Example:

export GMAIL_MCP_CREDENTIALS_FILE="C:/path/to/credentials.json"
export GMAIL_MCP_TOKEN_FILE="C:/path/to/token.json"

On Windows PowerShell:

$env:GMAIL_MCP_CREDENTIALS_FILE = "C:\path\to\credentials.json"
$env:GMAIL_MCP_TOKEN_FILE = "C:\path\to\token.json"

Run locally

sudo-mcp-gmail

Claude Desktop MCP config

Add a server entry pointing to the installed command. Example shape:

{
  "mcpServers": {
    "gmail": {
      "command": "sudo-mcp-gmail",
      "env": {
        "GMAIL_MCP_CREDENTIALS_FILE": "C:/path/to/credentials.json",
        "GMAIL_MCP_TOKEN_FILE": "C:/path/to/token.json"
      }
    }
  }
}

If your client requires launching via Python directly, use:

{
  "mcpServers": {
    "gmail": {
      "command": "python",
      "args": ["-m", "sudo_mcp_gmail.server"],
      "env": {
        "GMAIL_MCP_CREDENTIALS_FILE": "C:/path/to/credentials.json",
        "GMAIL_MCP_TOKEN_FILE": "C:/path/to/token.json"
      }
    }
  }
}

Codex or other MCP clients

Use the same pattern:

• command: sudo-mcp-gmail or python -m sudo_mcp_gmail.server
• pass the Gmail credentials/token file paths through environment variables

Attachment URL safety

Remote attachments support HTTPS URLs only.

Blocked attachment sources:

• http://...
• file://...
• https://localhost/...
• private-network or loopback IP targets such as https://127.0.0.1/... or https://192.168.1.10/...

Safety behavior:

• remote downloads are size-limited to 10 MB
• filenames are taken from Content-Disposition when available, otherwise from the URL path
• filenames are sanitized before attaching
• original filename and extension are preserved when safely available

Example prompts in an MCP client

• "Create a Gmail draft to jane@example.com with cc to finance@example.com, subject 'Q2 follow-up', body 'Please see attached', and attach C:/tmp/report.pdf."
• "Update Gmail draft r-1234567890 with a new subject and body."
• "Get the Gmail draft with ID r-1234567890."
• "Send the Gmail draft with ID r-1234567890."
• "Reply to message <message_id> with body 'Thanks, received.'"
• "Reply all to message <message_id> and attach C:/tmp/notes.txt."
• "Forward message <message_id> to jane@example.com with note 'Please review'."
• "List Gmail labels."
• "Mark message <message_id> as read."
• "Mark message <message_id> as unread."
• "Send an email to jane@example.com with subject 'Hello', body 'Checking in', and attach C:/tmp/agenda.docx."
• "Create a Gmail draft to jane@example.com and attach https://example.com/files/report.pdf."
• "Send an email to jane@example.com and attach https://example.com/files/invoice.pdf."
• "List my last 10 inbox emails."
• "Get message <message_id>."
• "Search my email for invoices from stripe.com in the last 30 days with attachments."

Security notes

• Keep credentials.json and token files private.
• Do not commit OAuth credentials or refresh tokens.
• This server uses the Gmail scope https://www.googleapis.com/auth/gmail.modify, which allows reading mailbox data, creating drafts, sending messages, replying, forwarding, and modifying labels/read state.
• Sending/replying/forwarding tools act immediately, so use them carefully.
• Remote attachment URLs are restricted to HTTPS and blocked for localhost/private-network targets.
• Remote attachment downloads are limited to 10 MB.

Build and publish the pip package

Build distributable artifacts:

python -m pip install --upgrade pip
pip install -e .[dev]
python -m build

This creates:

• dist/*.tar.gz — source distribution
• dist/*.whl — wheel distribution

Validate the package metadata before upload:

python -m twine check dist/*

Upload to TestPyPI first:

python -m twine upload --repository testpypi dist/*

Install from TestPyPI to verify:

pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple sudo-mcp-gmail

Upload to PyPI:

python -m twine upload dist/*

After publishing, anyone can install and run it with:

pip install sudo-mcp-gmail
sudo-mcp-gmail

Development

Install development tooling:

pip install -e .[dev]
pytest

Release checklist

1. Update the version in pyproject.toml and src/sudo_mcp_gmail/__init__.py.
2. Clear old build artifacts if needed.
3. Run pytest.
4. Run python -m build.
5. Run python -m twine check dist/*.
6. Upload to TestPyPI, verify install, then upload to PyPI.
7. Create a git tag matching the release version if you want versioned releases in GitHub.

Suggested future features

• archive/unarchive tools
• trash/untrash tools
• label add/remove tools for messages and threads
• thread-level tools
• download Gmail attachments
• pagination support for large searches
• unread/starred/important convenience filters
• better HTML sanitization or markdown-to-HTML support for outgoing messages
• attachment metadata in read/search results