gmail

This Gmail MCP server enables an MCP client to interact with a Gmail account to send, read, mark as read, trash, and open emails. The provided tools map to common email operations: send-email creates and sends messages to recipients; read-email fetches details of a specific message and marks it read; get-unread-emails retrieves a list of unread messages; mark-email-as-read updates a message's read status; trash-email moves a message to trash; and open-email launches the selected email in your default browser for quick viewing. The server is designed to require explicit user consent for operations that access or modify emails, aligning with privacy and security practices.

To use the server, start it through your preferred Python/UV flow as described in the setup, supplying the required credentials and token paths. The MCP client (for example Claude Desktop) will communicate with these tools via the defined endpoints. You can integrate the server by configuring your MCP client to run the Gmail server using the uv-based workflow demonstrated in the documentation, passing the credentials file path and token store path where appropriate. The tools themselves are exposed as discrete actions, enabling you to perform targeted email operations without exposing broader access to your Gmail account.

Access and permissions follow the Gmail API scopes configured during setup (notably https://www.googleapis.com/auth/gmail/modify). The client prompts user confirmation before performing read, delete, or send actions, ensuring deliberate user consent for potentially sensitive operations.

Prerequisites:

• Python 3.8+ installed
• uv (Python integration) available via your preferred workflow
• Access to a Google Cloud project with Gmail API enabled and OAuth credentials downloaded

Step-by-step installation:

1. Clone the MCP server repository (or download the Gmail server directory).

2. Install Python dependencies if a requirements file exists (example: python3 -m pip install -r requirements.txt).

3. Place your Gmail OAuth credentials JSON file somewhere secure and note its path. This will be provided to the server with --creds-file-path.

4. Prepare a location to store OAuth tokens (e.g., ~/.google/app_tokens.json). This will be provided with --token-path.

5. Start the server using the uv-based command described in the setup, for example:

   uv run /path/to/gmail/server.py --creds-file-path /path/to/creds.json --token-path /path/to/app_tokens.json

6. Verify the server starts and is reachable by the MCP client inspector or by issuing a test command through the MCP interface.

Note: If your environment uses a containerized workflow, adapt the uv invocation to your container entrypoint and ensure the credentials/token paths are mounted into the container.

Tips and troubleshooting:

• Ensure your OAuth client credentials JSON is kept secure and not committed to version control.
• The authentication flow will open a browser window for user consent; ensure a graphical environment or appropriate headless workaround is available.
• The token file path is where access/refresh tokens will be stored for subsequent runs; ensure the path is writable.
• When testing with MCP Inspector, you can simulate operations by issuing commands like get-unread-emails, read-email, and send-email to verify end-to-end behavior.
• If you switch environments (dev vs prod), remember to update the credentials and token paths accordingly and re-authenticate if needed.