Gmail-MCP-Server

# Gmail MCP Server A Node.js server that connects the Model Context Protocol (MCP) to Gmail, enabling large language models to send, read, and manage emails securely using the Gmail API. <p align="center"> <a href="https://github.com/nisalgunawardhana/Gmail-MCP-Server/watchers"> <img src="https://img.shields.io/github/watchers/nisalgunawardhana/Gmail-MCP-Server?style=social" alt="Watchers"/> </a> &nbsp; <a href="https://github.com/nisalgunawardhana/Gmail-MCP-Server/stars"> <img src="https://img.shields.io/github/stars/nisalgunawardhana/Gmail-MCP-Server?style=social" alt="Stars"/> </a> &nbsp; <a href="https://github.com/nisalgunawardhana/Gmail-MCP-Server/network/members"> <img src="https://img.shields.io/github/forks/nisalgunawardhana/Gmail-MCP-Server?style=social" alt="Forks"/> </a> </p> ## Features - 📤 Send emails through Gmail API - 📥 Get inbox emails with filtering options - 🔍 Advanced email search using Gmail query syntax - 📧 Retrieve specific emails by ID with full content - 📝 Access draft emails - 📬 View sent emails - 📎 Support for HTML and plain text emails - 📁 Attachment support (send and view) - 👥 CC and BCC recipients - 🔐 OAuth2 authentication with Google - 🛡️ Secure credential management - ⚡ Fast email operations with metadata caching ## Setup ### 1. Install Dependencies ```bash npm install ``` ### 2. Google Cloud Setup 1. Go to the [Google Cloud Console](https://console.cloud.google.com/) 2. Create a new project or select an existing one 3. Enable the Gmail API: - Go to "APIs & Services" > "Library" - Search for "Gmail API" and enable it 4. Create credentials: - Go to "APIs & Services" > "Credentials" - Click "Create Credentials" > "OAuth 2.0 Client IDs" - Choose "Desktop application" - Download the JSON file and rename it to `credentials.json` - Place it in the root directory of this project **Note**: Desktop applications automatically work with the out-of-band authentication flow, so no additional redirect URI configuration is needed. 5. Configure OAuth Consent Screen: - Go to "APIs & Services" > "OAuth consent screen" - Choose "External" user type (unless you have a Google Workspace) - Fill in the required fields: - App name: "Gmail MCP Server" (or your preferred name) - User support email: Your email address - Developer contact information: Your email address - Add your Gmail address to "Test users" section - This allows you to use the app in testing mode ### 3. Authentication Setup Complete OAuth authentication to allow the server to send emails: ```bash npm run setup ``` This will: 1. Check that `credentials.json` exists 2. Generate an authorization URL 3. Guide you through the OAuth flow 4. Save the authentication token #### 🔍 Finding Your Authorization Code After clicking "Allow" in the Google OAuth screen, you'll be redirected. Here's how to find your authorization code: **Method 1: Direct Code Display (Most Common for Desktop Apps)** - After clicking "Allow", Google shows the authorization code directly on a page - Look for text like "Please copy this code, switch to your application and paste it there:" - Copy the code from the text box or highlighted area **Example Authorization Code:** ``` 4/0AbCD1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890 ``` ⚠️ **Important**: The code is usually very long (50+ characters) and starts with `4/0` **Note**: The server reads OAuth credentials directly from `credentials.json`. You don't need to create a `.env` file unless you want to set optional configurations. ### Optional: Environment Configuration You can optionally create a `.env` file for additional settings: ```env # Optional: Default sender email (will use authenticated user's email if not set) DEFAULT_SENDER_EMAIL=your-email@gmail.com # Optional: Authorization code (for automated setup) AUTH_CODE=your_auth_code_here ``` Run the server for the first time to complete OAuth authentication: ```bash npm start ``` Follow the authentication flow in your browser and paste the authorization code when prompted. ## Usage ### MCP Client Configuration Add this server to your MCP client configuration: ```json { "mcpServers": { "gmail": { "command": "node", "args": ["/path/to/gmail-mcp-server/src/index.js"], "env": {} } } } ``` ### Available Tools #### send_email Send an email through Gmail. **Parameters:** - `to` (required): Recipient email address(es) - string or array of strings - `subject` (required): Email subject line - `body` (required): Email body content - `cc` (optional): CC recipient email address(es) - string or array of strings - `bcc` (optional): BCC recipient email address(es) - string or array of strings - `html` (optional): Set to true if body contains HTML content (default: false) - `attachments` (optional): Array of file paths to attach **Example:** ```json { "name": "send_email", "arguments": { "to": "recipient@example.com", "subject": "Hello from MCP Server", "body": "This is a test email sent through the Gmail MCP server.", "html": false } } ``` #### get_inbox_emails Retrieve emails from your inbox with optional filtering. **Parameters:** - `maxResults` (optional): Maximum number of emails to retrieve (default: 10) - `query` (optional): Gmail search query to filter emails (default: "in:inbox") - `includeSpamTrash` (optional): Include spam and trash emails (default: false) **Example:** ```json { "name": "get_inbox_emails", "arguments": { "maxResults": 5, "query": "is:unread" } } ``` #### get_email_by_id Get a specific email by its ID with full content including body and attachments. **Parameters:** - `emailId` (required): The ID of the email to retrieve - `format` (optional): Format of the email data - "full", "metadata", or "minimal" (default: "full") **Example:** ```json { "name": "get_email_by_id", "arguments": { "emailId": "1234567890abcdef", "format": "full" } } ``` #### search_emails Search emails using Gmail's powerful search query syntax. **Parameters:** - `query` (required): Gmail search query (e.g., "from:example@gmail.com", "subject:important", "has:attachment") - `maxResults` (optional): Maximum number of emails to retrieve (default: 10) **Example:** ```json { "name": "search_emails", "arguments": { "query": "from:boss@company.com has:attachment", "maxResults": 20 } } ``` #### get_sent_emails Retrieve emails from your sent folder. **Parameters:** - `maxResults` (optional): Maximum number of emails to retrieve (default: 10) **Example:** ```json { "name": "get_sent_emails", "arguments": { "maxResults": 15 } } ``` #### get_draft_emails Retrieve draft emails. **Parameters:** - `maxResults` (optional): Maximum number of draft emails to retrieve (default: 10) **Example:** ```json { "name": "get_draft_emails", "arguments": { "maxResults": 5 } } ``` ### Gmail Search Query Examples The `search_emails` and `get_inbox_emails` tools support Gmail's powerful search syntax: - `from:sender@example.com` - Emails from specific sender - `to:recipient@example.com` - Emails to specific recipient - `subject:keyword` - Emails with keyword in subject - `has:attachment` - Emails with attachments - `is:unread` - Unread emails - `is:important` - Important emails - `newer_than:7d` - Emails newer than 7 days - `older_than:1m` - Emails older than 1 month - `size:larger_than:10M` - Emails larger than 10MB You can combine multiple criteria: - `from:boss@company.com is:unread has:attachment` - `subject:meeting newer_than:3d` - `to:me filename:pdf older_than:1w` ## Security Notes - OAuth2 tokens are stored locally in `token.json` - Never commit `credentials.json`, `token.json`, or `.env` files to version control - The server requires explicit user consent for Gmail access - All API calls use Google's official Gmail API with proper authentication ## Troubleshooting ### "Insufficient Permission" Errors **This is the most common issue when upgrading from send-only to full email access.** **Quick Fix:** ```bash # Delete old token and re-authenticate rm token.json npm run setup ``` **Or use the dedicated re-auth script:** ```bash npm run reauth ``` **Why this happens:** The original authentication only requested `gmail.send` permission. The new email reading features require additional scopes (`gmail.readonly` and `gmail.modify`). ### OAuth 403: access_denied Error If you encounter "Error 403: access_denied" or "app is currently being tested", follow these steps: #### Quick Fix (Recommended for Personal Use): 1. **Add yourself as a test user**: - Go to [Google Cloud Console](https://console.cloud.google.com/) - Navigate to "APIs & Services" > "OAuth consent screen" - Scroll down to "Test users" section - Click "ADD USERS" and add your Gmail address - Save the changes 2. **Ensure correct user type**: - In OAuth consent screen, make sure you selected "External" user type - If you selected "Internal" but don't have Google Workspace, change to "External" 3. **Clear browser cache and try again**: - Clear your browser's cache and cookies for Google accounts - Try the authentication flow again #### Alternative: Use App Passwords (Gmail Specific) If OAuth continues to be problematic, you can use Gmail App Passwords: 1. **Enable 2-Factor Authentication** on your Google account 2. **Generate an App Password**: - Go to Google Account settings - Security > 2-Step Verification > App passwords - Generate a password for "Mail" 3. **Use SMTP instead of Gmail API** (requires code modification) #### For Production Use: To remove the testing limitation permanently: 1. Complete the OAuth consent screen with all required information 2. Submit for Google verification (takes 1-4 weeks) 3. Provide privacy policy, terms of service, and app homepage 4. Once verified, any Gmail user can authorize your app ### Other Common Issues #### "credentials.json not found" - Ensure the file is in the project root directory - Check the filename is exactly `credentials.json` - Verify the file contains valid JSON #### "Token refresh failed" - Delete `token.json` file - Run `npm run setup` to re-authenticate - Ensure your OAuth2 credentials are still valid #### "Gmail API not enabled" - Go to Google Cloud Console - Navigate to "APIs & Services" > "Library" - Search for "Gmail API" and ensure it's enabled ## 🔄 Important: Re-authentication Required for Email Reading **If you previously set up this server for sending emails only**, you'll need to re-authenticate to access inbox and email reading features. The original setup only requested `gmail.send` permission, but the new features require additional scopes. ### Quick Fix for "Insufficient Permission" Errors: 1. **Delete the existing token**: ```bash rm token.json ``` 2. **Re-run the setup** (this will request the additional permissions): ```bash npm run setup ``` 3. **Follow the OAuth flow again** - this time it will request permissions for: - Send emails (`gmail.send`) - Read emails (`gmail.readonly`) - Modify emails (`gmail.modify`) ### Alternative: Force Re-authentication Script If you prefer a dedicated script: ```bash npm run reauth ``` ## Development ```bash # Start with auto-reload npm run dev # Run tests npm run test ``` ## Contributing We welcome contributions to the Gmail MCP Server! Here's how you can help: ### 🚀 Getting Started 1. **Fork the repository** on GitHub 2. **Clone your fork** locally: ```bash git clone https://github.com/your-username/email-mcp-server.git cd email-mcp-server ``` 3. **Install dependencies**: ```bash npm install ``` 4. **Set up authentication** (see Setup section above): ```bash npm run setup ``` ### 🔧 Development Workflow 1. **Create a feature branch**: ```bash git checkout -b feature/your-feature-name ``` 2. **Make your changes** following our coding standards 3. **Test your changes**: ```bash npm run test ``` 4. **Run the server locally** to verify functionality: ```bash npm run dev ``` 5. **Commit your changes** with a descriptive message: ```bash git commit -m "feat: add support for email labels" ``` 6. **Push to your fork**: ```bash git push origin feature/your-feature-name ``` 7. **Create a Pull Request** on GitHub ### 📝 Coding Standards - **JavaScript Style**: Use modern ES6+ syntax - **Formatting**: Run `npm run lint` (if available) before committing - **Comments**: Add JSDoc comments for functions and complex logic - **Error Handling**: Always include proper error handling and validation - **Security**: Never log or expose sensitive credentials ### 🧪 Testing Guidelines - **Write tests** for new features in the `test/` directory - **Test email functionality** with the provided test scripts: ```bash node test/send-test-email.js node test/email-operations-test.js ``` - **Verify MCP integration** with the test client: ```bash node test/mcp-test-client.js ``` ### 📋 What We're Looking For **High Priority:** - 📎 Enhanced attachment handling (multiple files, size limits) - 🏷️ Email label management (create, apply, remove labels) - 📤 Draft management (create, edit, send drafts) - 🔄 Real-time email notifications via webhooks - 📊 Email analytics and reporting features **Medium Priority:** - 🎨 HTML email template support - 📋 Email signature management - 🔍 Advanced search filters and sorting - 📱 Mobile-friendly authentication flow - 🌐 Multi-language support **Always Welcome:** - 🐛 Bug fixes and security improvements - 📚 Documentation enhancements - ⚡ Performance optimizations - 🧪 Additional test coverage ### 🐛 Reporting Issues When reporting bugs, please include: 1. **Clear description** of the issue 2. **Steps to reproduce** the problem 3. **Expected vs actual behavior** 4. **Environment details**: - Node.js version (`node --version`) - npm version (`npm --version`) - Operating system 5. **Error messages** or logs (remove sensitive information) 6. **Code snippets** if relevant ### 📋 Issue Templates We provide issue templates to help you report bugs and request features effectively: #### 🐛 Bug Report Template Use this template when reporting bugs or unexpected behavior: - **Summary**: Brief description of the issue - **Environment**: Node.js version, OS, npm version - **Steps to Reproduce**: Numbered steps to recreate the issue - **Expected Behavior**: What should happen - **Actual Behavior**: What actually happens - **Error Messages**: Any error logs or messages - **Additional Context**: Screenshots, code snippets, or other relevant info #### ✨ Feature Request Template Use this template when suggesting new features: - **Feature Summary**: Brief description of the proposed feature - **Problem Statement**: What problem does this solve? - **Proposed Solution**: How should this feature work? - **Use Case**: Real-world scenarios where this would be helpful - **Alternatives Considered**: Other solutions you've thought about - **Additional Context**: Mockups, examples, or references #### 📚 Documentation Issue Template Use this template for documentation improvements: - **Documentation Section**: Which part needs improvement - **Issue Description**: What's unclear or missing - **Suggested Improvement**: How to make it better - **Target Audience**: Who would benefit from this change #### 🔧 How to Create an Issue 1. **Visit the Issues page**: Go to the repository's [Issues tab](https://github.com/nisalgunawardhana/email-mcp-server/issues) 2. **Click "New Issue"**: Start creating a new issue 3. **Choose a template**: Select the appropriate template (Bug Report, Feature Request, etc.) 4. **Fill out the template**: Complete all relevant sections 5. **Add labels**: Apply appropriate labels (bug, enhancement, documentation, etc.) 6. **Submit**: Click "Submit new issue" #### 📝 Issue Labels Guide We use these labels to categorize issues: **Type Labels:** - `bug` - Something isn't working - `enhancement` - New feature or request - `documentation` - Improvements or additions to documentation - `question` - Further information is requested - `help wanted` - Extra attention is needed - `good first issue` - Good for newcomers **Priority Labels:** - `priority: high` - Critical issues that need immediate attention - `priority: medium` - Important issues that should be addressed soon - `priority: low` - Nice-to-have improvements **Component Labels:** - `gmail-api` - Related to Gmail API integration - `authentication` - OAuth and credential management - `mcp` - Model Context Protocol functionality - `testing` - Test-related issues - `security` - Security-related concerns #### 🔍 Before Creating an Issue **Search First**: Check if someone has already reported the same issue or requested the same feature. **For Bugs:** - Try the latest version to see if the issue is already fixed - Check the troubleshooting section in the README - Test with different configurations if possible **For Features:** - Consider if this fits the project's scope and goals - Think about how it would affect existing functionality - Look for similar features in related projects ### 💡 Feature Requests For new features: 1. **Check existing issues** to avoid duplicates 2. **Describe the use case** and why it's valuable 3. **Provide examples** of how it would work 4. **Consider backwards compatibility** ### 🏷️ Commit Message Format We follow conventional commits: ``` type(scope): description [optional body] [optional footer] ``` **Types:** - `feat`: New feature - `fix`: Bug fix - `docs`: Documentation changes - `style`: Code style changes (no logic changes) - `refactor`: Code refactoring - `test`: Adding or updating tests - `chore`: Maintenance tasks **Examples:** ``` feat(gmail): add support for email labels fix(auth): handle token refresh edge case docs(readme): update API documentation test(email): add unit tests for validation ``` ### 📄 License By contributing, you agree that your contributions will be licensed under the MIT License. ### 🤝 Code of Conduct - Be respectful and inclusive - Focus on constructive feedback - Help others learn and grow - Follow the golden rule ### ❓ Questions? - Open an issue for questions about the codebase - Check existing documentation first - Be specific about what you're trying to achieve ## 👤 Author **Nisal Gunawardhana** - [GitHub](https://github.com/nisalgunawardhana) &nbsp; [](https://github.com/nisalgunawardhana) - [Twitter/X](https://twitter.com/thenisal) - [LinkedIn](https://www.linkedin.com/in/nisalgunawardhana/) Feel free to connect or follow for updates and new projects! Thank you for contributing to Gmail MCP Server! 🚀