gmail

This Gmail MCP server provides a set of tools to interact with a Gmail account via the MCP framework. It includes capabilities to send emails, read and read-unread emails, mark emails as read, move emails to trash, and open emails in a browser. The tools exposed are send-email, trash-email, mark-email-as-read, get-unread-emails, read-email, and open-email. Note that destructive actions such as reading, trashing, or replying to emails are typically guarded by user prompts in the client to prevent unintended operations. To use the server, configure your MCP client to reference the gmail server and invoke the specific tool you need with the required inputs (e.g., recipient_id, email_id). The authentication flow uses OAuth 2.0 via a credentials file and token file, so ensure you have completed the Gmail API setup and supplied the correct file paths when starting the server.

Prerequisites:

• Python environment with uv installed (via the uvx package).
• Google Cloud project with Gmail API enabled and OAuth credentials downloaded as a JSON file.
• Access to a machine where you can run the MCP client and the uvx-based server configuration.

Install and configure:

1. Install uvx (Python/uv) if not already installed. Example:

   pip install uvx

2. Prepare Gmail API credentials:

   • Create a Google Cloud project, enable Gmail API, and configure OAuth consent screen.
   • Create an OAuth Client ID for Desktop App and download the JSON key file.
   • Place credentials file somewhere secure and note its absolute path. This will be passed as --creds-file-path.
   • Run the authentication flow to produce and store tokens at the path provided with --token-path.

3. Setup MCP integration (example for Claude Desktop):

   • Ensure uvx is available and your Gmail server repo is accessible.
   • Use your MCP client to reference the server with the appropriate directory and file paths as shown below in the configuration.

4. Start the server via MCP configuration (example invocation will be provided by your MCP client).

Tips and common issues:

• Ensure the credentials and token paths are absolute paths and the files are accessible by the running process.
• The OAuth flow will launch in your system browser on first run; subsequent runs should use the stored token.
• If you change credentials, delete or refresh the token file to re-authenticate.
• If you encounter permission errors, double-check that the Gmail API scope includes https://www.googleapis.com/auth/gmail/modify as recommended by the setup guide.
• When integrating with a desktop client like Claude, ensure the --directory path points to the repository folder containing the gmail server and that the client can access the credentials and token files.
• The tools exposed (send-email, trash-email, mark-email-as-read, get-unread-emails, read-email, open-email) have specific input requirements as described in the server documentation. Build your requests to match those inputs.