Gmail MCP Server

A Model Context Protocol (MCP) server implementation for Gmail integration, enabling AI assistants to interact with Gmail through a standardized interface.

Features

• Email Operations

  • List and search emails with advanced filtering

  • Read email content with attachments

  • Send emails with attachments

  • Draft support (coming soon)

  • Reply/Forward support (coming soon)

• Label Management

  • List all labels

  • Create new labels

  • Update existing labels

  • Delete labels

• Authentication

  • Secure OAuth2 authentication

  • Automatic token refresh

  • Token persistence

Installation

1. Clone the repository:

git clone https://github.com/yourusername/gmail-mcp.git
cd gmail-mcp

2. Install dependencies:

npm install

3. Set up Google Cloud Project:

   • Go to Google Cloud Console

   • Create a new project

   • Enable Gmail API

   • Configure OAuth consent screen

   • Create OAuth credentials

   • Download credentials as gcp-oauth.keys.json

4. Configure the project:

   • Place gcp-oauth.keys.json in the project root directory

   • Run the authentication server:

npm run auth

5. Build the project:

npm run build

Usage

Starting the Server

npm start

The server runs on stdio, making it compatible with MCP clients.

Available Tools

1. List Emails

{
  "name": "list-emails",
  "arguments": {
    "maxResults": 10,
    "labelIds": ["INBOX"],
    "query": "is:unread"
  }
}

2. Read Email

{
  "name": "read-email",
  "arguments": {
    "id": "message-id",
    "format": "full"
  }
}

3. Send Email

{
  "name": "send-email",
  "arguments": {
    "to": "recipient@example.com",
    "subject": "Hello",
    "body": "Message content",
    "attachments": ["/path/to/file.pdf"]
  }
}

4. Search Emails

{
  "name": "search-emails",
  "arguments": {
    "query": "from:sender@example.com",
    "maxResults": 5
  }
}

5. Manage Labels

{
  "name": "manage-labels",
  "arguments": {
    "action": "create",
    "name": "MyNewLabel"
  }
}

Configuration

Environment Variables

• GMAIL_MCP_DEBUG: Enable debug logging (default: false)

• GMAIL_MCP_TOKEN_PATH: Custom path for token storage

• GMAIL_MCP_KEYS_PATH: Custom path for OAuth keys file

OAuth Credentials

The OAuth credentials file (gcp-oauth.keys.json) should be structured as:

{
  "installed": {
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "redirect_uris": ["http://localhost:3000/oauth2callback"]
  }
}

Development

Running Tests

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run in watch mode
npm run test:watch

Building

# Build once
npm run build

# Build in watch mode
npm run dev

Error Handling

The server handles various error scenarios:

• Authentication failures

• Rate limiting

• Invalid parameters

• Network issues

• Permission errors

Errors are returned in a standardized format with appropriate HTTP status codes.

Contributing

1. Fork the repository

2. Create your feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Google Gmail API

• Model Context Protocol

• Contributors and maintainers

Support

For support, please open an issue in the GitHub repository or contact the maintainers.