Yagms

🚀 Yet Another Gmail MCP Server

This project provides a tool to interact with your Gmail account through the Model Context Protocol (MCP).

🚀 Quick Start

✨ Features

The Gmail MCP Server offers tools to interact with your Gmail account via the Model Context Protocol (MCP).

📦 Installation

Prerequisites

1. Create OAuth credentials for the Gmail API:
   • Go to Google Cloud Console.
   • Create a new project or select an existing one.
   • Enable the Gmail API.
   • Create OAuth 2.0 credentials (Desktop app).
   • Download the credentials JSON file and save it as ~/.yagms-oauth.keys.json.

Build the Project

1. Install Bun.
2. Build the code:

bun install
bun run build-gmail # Will output to ./dist/gmail.js

Authentication

Before using the Gmail MCP Server, you need to authenticate:

# Run the authentication process
bun run dist/gmail.js auth

This will:

• Open a browser window for you to log in to your Google account.
• Request permission to access your Gmail account.
• Save the authentication credentials to ~/.yagms-credentials.json.

Run the Server

After authentication, you can run the Gmail MCP Server:

# Start the server
bun run src/gmail.ts

Configuration

You can customize the paths of OAuth credentials and credentials through environment variables:

• GMAIL_OAUTH_PATH: Path to the OAuth credentials file (Default: ~/.yagms-oauth.keys.json).
• GMAIL_CREDENTIALS_PATH: Path to save the credentials (Default: ~/.yagms-credentials.json).

💻 Usage Examples

Available Tools

The Gmail MCP Server provides the following tools:

1. list-emails: Get emails in your inbox.

   • Parameters:
     • senderEmail (Optional): Filter by sender's email.
     • maxResults (Optional, Default: 10): Maximum number of emails to return.
     • labelIds (Optional, Default: ["INBOX"]): Filter by label IDs.

2. get-email: Get a specific email by ID.

   • Parameters:
     • emailId: ID of the email to retrieve.

3. search-emails: Search for emails using Gmail search syntax.

   • Parameters:
     • query: Gmail search query (e.g., "from:example@gmail.com has:attachment").
     • maxResults (Optional, Default: 10): Maximum number of emails to return.

4. get-labels: Get all Gmail labels.

   • No parameters required.

Example MCP Configuration

Add this content to your MCP settings file:

{
  "mcpServers": {
    "gmail": {
      "command": "bun",
      "args": ["run", "/path/to/yagms/dist/gmail.js"],
      "env": {},
      "disabled": false,
      "autoApprove": []
    }
  }
}