gmail

This MCP server exposes Gmail’s API through the Model Context Protocol (MCP) so large language models and clients like Claude Desktop can interact with Gmail via a stable MCP interface. The server implements a set of tools that allow you to list and manage labels, as well as read and organize emails. Available tools include getting all labels, retrieving a label by ID, creating/updating/deleting labels, marking emails as read or unread, applying labels to multiple emails, paginating through email IDs based on a query, and fetching full email details. To use it, start the server with the required Google OAuth credentials (GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET), then configure your MCP consumer (e.g., Claude Desktop) to point at the running server using the provided command and environment variables. Once running, you can invoke these tools through your MCP client, passing the appropriate parameters (e.g., label IDs, email IDs, or query strings) as documented in the server’s tool definitions.

Prerequisites:

• Python 3.11 or newer
• A Google Cloud project with Gmail API enabled and OAuth 2.0 credentials (Client ID and Client Secret)
• Internet access to install dependencies

Installation steps:

1. Clone the repository

git clone <URL_DEL_REPOSITORIO>
cd gmail-mcp-server

2. Install uv and project dependencies

# Using uv as described in the project
uv pip install -r uv.lock

3. (Optional) Build/package the module

uv pip install build
uv run -m build

4. Install the packaged wheel locally (adjust version as needed)

uv pip install dist/gmail_mcp_server-0.1.1-py3-none-any.whl

5. Run the MCP server (provide Google OAuth credentials via environment variables)

GOOGLE_CLIENT_ID=your-client-id \
GOOGLE_CLIENT_SECRET=your-client-secret \
uv run -m gmail_mcp_server.main

6. Verify the server is running and accessible via the MCP client configuration (e.g., Claude Desktop) using the command and the env vars above.

If you prefer a direct Python run without uv tooling, you can also run:

GOOGLE_CLIENT_ID=your-client-id \
GOOGLE_CLIENT_SECRET=your-client-secret \
python -m gmail_mcp_server.main

Tips and common issues:

• Ensure Google OAuth credentials are correctly configured as environment variables: GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET.
• The server expects a desktop-type OAuth flow; you may need to complete the consent screen flow in a browser during the first run to obtain tokens.
• If you modify dependencies, update uv.lock accordingly and reinstall dependencies using uv pip install -r uv.lock.
• When configuring Claude Desktop or other MCP clients, reference the running command (e.g., gmail_mcp_server.main) and provide the same environment variables for OAuth.
• If running on Windows, you may need to adjust the path and ensure the shell environment exports GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET correctly.
• For troubleshooting, check the server logs for OAuth failures, API quota limits, or invalid label/email IDs passed to tools.