gmail

The Gmail MCP server provides programmatic access to Google’s Gmail API through OAuth2 authentication, enabling you to send emails, manage labels, create filters, and handle attachments via your IDE’s AI assistants. It exposes a set of 19 operations categorized into Email Operations, Label Management, and Filter Management, allowing you to perform tasks such as sending and drafting emails, reading messages with MIME parsing, applying labels, and creating Gmail filters. This server is designed to integrate with Cursor Cloud Geminis and similar IDE integrations, so you can manage Gmail directly from your development environment using natural language prompts or structured API calls.

To use it, install the MCP server package, build the project, and configure the MCP setup for your IDE. After authentication with Gmail, you can invoke operations like sending an email, searching for messages, or batch-modifying labels through your IDE’s command palette or chat interface. The integration supports proactive suggestions and transparent feedback, so you can see exactly which Gmail actions were performed and handle errors gracefully.

Prerequisites:

• Node.js 18.0.0+ and npm
• A Google Cloud Project with Gmail API enabled
• OAuth 2.0 credentials (Desktop or Web application) and a credentials JSON file

Step-by-step installation:

1. Install Node.js and npm from the official Node.js website if not already installed.
2. Clone the repository: git clone https://github.com/pouyanafisi/gmail-mcp.git cd gmail-mcp
3. Install dependencies: npm install
4. Build the project (TypeScript to JavaScript): npm run build
5. Run the setup to configure MCP for your IDE (Cursor IDE in quick-start example): npm run setup
6. Authenticate with Gmail: npm run auth
7. Start the MCP server using the Node entry point (adjust the path as needed): node dist/index.js

Optional local/global npm install:

• Global install (recommended for CLI access): npm install -g @pouyanafisi/gmail-mcp
• Local install (per-project): npm install @pouyanafisi/gmail-mcp

Environment and configuration tips:

• Ensure Gmail API is enabled and OAuth credentials are correctly configured. Credentials can be saved to ~/.gmail-mcp/credentials.json and auto-refreshed.
• If using source installation, the MCP entry point is typically dist/index.js after a successful npm run build. Update the path in mcp_config accordingly.
• For IDE integration, the setup command will generate platform-specific instructions and verify credentials. If you encounter authentication issues, re-run npm run auth or inspect the credentials file location.
• When running in cloud environments, configure a callback URL appropriate to your deployment and provide it during the auth flow.
• The server supports both global and local npm installation modes; adjust the mcp_config command and args accordingly (npx usage for local installs).
• Keep Node.js updated to match the required version to ensure compatibility with TypeScript output and Gmail API client libraries.