MCP Gmail Server

🚀 Gmail MCP Server

This Gmail MCP Server enables interaction with Gmail accounts via natural - language instructions, supporting email search and reading.

🚀 Quick Start

To use the Gmail MCP Server, you need to configure the Gmail API key and OAuth credentials in the src/main/resources/credentials.json file. Also, ensure that the JVM system property -Dgmail.credentials.path=src/main/resources is set correctly. Before running the server, complete the following authentication steps:

1. Create a project and enable the Gmail API.
2. Enable the Cloud Platform API service.
3. Create OAuth credentials.

✨ Features

Search Emails

Search for emails using natural language or query strings. The following operation is supported:

searchEmails(query: String) -> List<Email>

Read Emails

Read the full content of an email based on its ID:

readEmail(emailId: String) -> Email

📦 Installation

• credentials.json: Contains the credential information for the Gmail API.
• src/main/resources/: Ensure that the configuration file is located in this directory.
• -Dgmail.credentials.path=src/main/resources: Set the JVM system property.

💻 Usage Examples

Basic Usage

• Search by Subject:

  Show emails about budget approvals in the past month.
  

  Translates to: searchEmails("budget approvals after:2025-03-01 before:2025-04-01")

• Search by Sender:

  Find emails about conference planning sent by alice@example.com.
  

  Translates to: searchEmails("from:alice@example.com conference planning")

📚 Documentation

Best Practices

• Security:

  • Use the minimum permission scope gmail.readonly to limit access.
  • Store credential files and tokens in a secure location, such as excluding them in .gitignore.

• Error Handling:

  • Return JSON - RPC error responses to handle invalid requests or API failures.
  • Use SLF4J/Logback for detailed logging to assist with debugging.

Troubleshooting

• Authentication Errors:
  • Ensure that the credentials.json file is located in the src/main/resources/ directory.
  • Delete ~/.gmail - mcp/tokens and re - authenticate.

Security Considerations

• Credentials: Ensure that credentials.json and ~/.gmail - mcp/tokens are not accidentally committed to the version control system.
• OAuth2: Use the offline access type for continuous token access; regularly check the activity logs in the Google Cloud Console.

Extending the Server

• Adding Features: Extend GmailMcpServer.java to include more features, such as labelEmail or sendEmail (additional scopes required).
• Remote Deployment: Use SSE or WebSocket for cloud deployment (e.g., using Spring WebFlux).
• Caching: Implement a caching mechanism for common queries using in - memory storage like Caffeine.

Contribution Guidelines

Contributions are welcome! Please follow these steps:

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/xyz).
3. Commit your changes (git commit -m "Add XYZ feature").
4. Push to the branch (git push origin feature/xyz).
5. Submit a pull request.

📄 License

[License information]

👏 Acknowledgments

Thanks to the following contributors:

• [Contributor Name]
• [Other Contributor Name]