Gmail Multi-Inbox MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to manage multiple Gmail accounts simultaneously with built-in OAuth authentication.

Agent CLI

All 60 Gmail, Drive, Sheets, Docs, Calendar, and account tools are also available as noninteractive CLI calls with structured JSON, schema discovery, bounded output, and explicit error/exit codes:

ghub tools
ghub schema search_emails
ghub call list_accounts

See the agent CLI quickstart for input files/stdin, pagination, validation-only dry runs, and OAuth setup. CLI and MCP share the same accounts and Google clients. Bare ghub and ghub mcp still start MCP; use ghub --help for JSON CLI help. From a built checkout, commands can also be run with node dist/index.js in place of ghub.

Why This MCP Server?

Unlike existing Gmail MCP servers, this implementation offers:

Multi-Account Support: Manage multiple Gmail accounts from a single MCP server instance
Intelligent Aggregation: Read and search across all accounts simultaneously
Built-in OAuth Flow: Complete authentication setup through MCP tools - no manual token generation
Type-Safe: Built with TypeScript for reliability and better IDE support
Auto Token Refresh: Handles token expiration automatically and saves refreshed tokens
Comprehensive API: Full Gmail API coverage including labels, threads, drafts, and more

Features

Read Operations

list_accounts - View all configured accounts and their status
read_emails - Fetch recent emails (aggregates across all accounts by default)
search_emails - Search using Gmail query syntax across multiple accounts
get_email_thread - Retrieve complete conversation threads
get_labels - List all labels for an account

Write Operations

send_email - Send emails from any configured account, with optional local file attachments
create_draft - Create draft messages, with optional local file attachments
delete_drafts - Permanently delete one or more drafts by draft ID
mark_as_read - Mark messages as read
archive_emails - Archive messages (remove from inbox)
trash_emails - Move messages to trash

Label Management

add_labels - Apply labels to messages
remove_labels - Remove labels from messages
create_label - Create new custom labels
delete_label - Delete existing labels

Account Management

begin_account_auth - Start OAuth flow for new account
finish_account_auth - Complete OAuth and save credentials

Prerequisites

Node.js 20+ (Download)
A Google Cloud Project with Gmail API enabled, plus Drive, Sheets, Docs, and Calendar APIs for the corresponding tools
OAuth 2.0 Credentials (Desktop application type)

Installation

# Clone the repository
git clone https://github.com/tszaks/gmail-multi-inbox-mcp.git
cd gmail-multi-inbox-mcp

# Install dependencies
npm install

# Build the TypeScript code
npm run build

Google Cloud Setup

Before using this MCP server, you need to set up a Google Cloud project:

1. Create a Google Cloud Project

Go to Google Cloud Console
Create a new project or select an existing one
Note your project ID

2. Enable Gmail API

In your project, go to APIs & Services > Library
Search for "Gmail API"
Click Enable
Enable Google Drive, Google Sheets, Google Docs, and Google Calendar APIs for the corresponding tools you plan to use.

3. Create OAuth 2.0 Credentials

Go to APIs & Services > Credentials
Click + CREATE CREDENTIALS > OAuth client ID
If prompted, configure the OAuth consent screen:
- Choose "External" user type
- Fill in required fields (app name, support email)
- Add your email to test users
For application type, select Desktop app
Give it a name (e.g., "Gmail MCP Client")
Click Create
Download the JSON file - you'll need this for authentication

4. OAuth Consent Screen Setup

Go to APIs & Services > OAuth consent screen
Review the existing broad scopes requested by GHub:
- https://mail.google.com/
- https://www.googleapis.com/auth/gmail.settings.basic
- https://www.googleapis.com/auth/drive
- https://www.googleapis.com/auth/spreadsheets
- https://www.googleapis.com/auth/documents
- https://www.googleapis.com/auth/calendar
Add your Gmail address(es) as test users

These scopes permit writes and are unchanged by the CLI. Human consent is required during the separate OAuth onboarding flow.

Configuration

Add to Your MCP Settings

Add this server to your .mcp.json configuration file (adjust path to match your installation):

{
  "mcpServers": {
    "gmail-multi": {
      "command": "node",
      "args": [
        "/path/to/gmail-multi-inbox-mcp/dist/index.js"
      ]
    }
  }
}

Custom Config Directory (Optional)

To use a custom directory for storing account data:

{
  "mcpServers": {
    "gmail-multi": {
      "command": "node",
      "args": [
        "/path/to/gmail-multi-inbox-mcp/dist/index.js"
      ],
      "env": {
        "GMAILMCPCONFIG_DIR": "/custom/path/.gmail-multi-mcp"
      }
    }
  }
}

The server also accepts the legacy GMAIL_MCP_CONFIG_DIR env var.

Directory Structure

Default configuration location: ~/.gmail-multi-mcp/

~/.gmail-multi-mcp/
├── accounts.json           # Master account list
└── accounts/
    ├── personal/
    │   ├── credentials.json  # OAuth client credentials
    │   ├── token.json       # Access/refresh tokens
    │   └── meta.json        # Account metadata
    └── work/
        ├── credentials.json
        ├── token.json
        └── meta.json

accounts.json Format

{
  "defaultAccount": "personal",
  "accounts": [
    {
      "id": "personal",
      "email": "user@gmail.com",
      "displayName": "Personal Gmail",
      "enabled": true,
      "credentialPath": "~/.gmail-multi-mcp/accounts/personal/credentials.json",
      "tokenPath": "~/.gmail-multi-mcp/accounts/personal/token.json"
    },
    {
      "id": "work",
      "email": "user@company.com",
      "displayName": "Work Email",
      "enabled": true,
      "credentialPath": "~/.gmail-multi-mcp/accounts/work/credentials.json",
      "tokenPath": "~/.gmail-multi-mcp/accounts/work/token.json"
    }
  ]
}

Railway / SSE Deployment

This server can run as either stdio MCP or an SSE-backed HTTP server.

Set MCP_TRANSPORT=sse to force HTTP/SSE mode.
If PORT is present, the server automatically switches to SSE mode.
The SSE endpoint is served at /sse and message posts are accepted at /messages.
Configuration still respects GMAILMCPCONFIG_DIR and GMAIL_MCP_CONFIG_DIR.

For Railway, point the start command at npm start or node dist/index.js and let Railway provide PORT.

OAuth Onboarding

Authenticate accounts directly through MCP tools:

Step 1: Start Authentication

Call the begin_account_auth tool with your OAuth credentials:

{
  "account_id": "personal",
  "email": "user@gmail.com",
  "credentials_json": {
    "installed": {
      "client_id": "YOUR_CLIENT_ID.apps.googleusercontent.com",
      "client_secret": "YOUR_CLIENT_SECRET",
      "redirect_uris": ["http://localhost"]
    }
  }
}

Or use a file path:

{
  "account_id": "personal",
  "email": "user@gmail.com",
  "credentials_path": "/path/to/credentials.json"
}

The tool returns a Google OAuth URL. Open this URL in your browser.

Step 2: Complete Authentication

In your browser, sign in with the Gmail account
Grant the requested permissions
Google redirects you to a localhost URL with a code parameter
Copy the authorization code from the URL

Call finish_account_auth:

{
  "account_id": "personal",
  "authorization_code": "4/0AfJoh..."
}

Your account is now authenticated and ready to use.

Usage Examples

Example 1: Read Recent Emails from All Accounts

// Aggregates across all enabled accounts
{
  "max_results": 20,
  "include_body": true
}

// Returns emails with source account indicated

Example 2: Search Across Multiple Accounts

{
  "query": "from:boss@company.com is:unread",
  "max_results": 10
}

// Searches all enabled accounts, merges and sorts results

Example 3: Send Email from Specific Account

{
  "account": "work",
  "to": "colleague@company.com",
  "subject": "Project Update",
  "body": "Here's the latest on the project...",
  "html": false
}

Example 4: Read Only from One Account

{
  "account": "personal",
  "max_results": 10,
  "query": "label:important"
}

Example 5: Manage Labels

// Create a new label
{
  "account": "personal",
  "name": "Urgent-2026"
}

// Add label to messages
{
  "account": "personal",
  "message_ids": ["msg123", "msg456"],
  "label_ids": ["Label_789"]
}

Example 6: Delete Drafts

// Delete one or more drafts by their draft IDs (returned by create_draft)
{
  "account": "personal",
  "draft_ids": ["r5457071851533655344", "r774137312565667821"]
}

API Reference

Read Operations

`list_accounts`

Returns all configured accounts with health status.

Parameters: None

Returns:

{
  accounts: Array<{
    id: string
    email: string
    displayName: string
    enabled: boolean
    hasValidToken: boolean
  }>
}

`read_emails`

Fetch recent emails with optional filtering.

Parameters:

account (optional): Account ID to read from. Omit to aggregate all accounts.
max_results (optional, default: 20): Number of emails to return (1-100)
query (optional): Gmail search query
include_body (optional, default: false): Include plaintext body extraction

Returns: Array of email objects with metadata, headers, and optional body

`search_emails`

Search emails using Gmail query syntax.

Parameters:

query (required): Gmail search query
account (optional): Account ID to search. Omit to search all accounts.
max_results (optional, default: 25): Maximum results (1-100)

Returns: Array of matching emails

`get_email_thread`

Retrieve a complete email thread.

Parameters:

account (required): Account ID
thread_id (required): Gmail thread ID

Returns: Thread object with all messages

`get_labels`

List all labels for an account.

Parameters:

account (required): Account ID

Returns: Array of label objects with IDs and names

Write Operations

`send_email`

Send an email from a specific account.

Parameters:

account (required): Account ID
to (required): Recipient email address(es)
subject (required): Email subject
body (required): Email body
cc (optional): CC recipients
bcc (optional): BCC recipients
html (optional, default: false): Send as HTML
attachments (optional): Array of local file attachments. Each item supports:
- path (required): Absolute path to the file (a leading ~ is expanded). A plain path string is also accepted in place of the object. A path that cannot be read fails the call instead of sending without it
- filename (optional): Override the filename shown in Gmail
- content_type (optional): Override the MIME type, for example application/pdf
thread_id (optional): Send as a reply in this Gmail thread
in_reply_to (optional): Message-ID being replied to. Derived from thread_id when omitted
references (optional): References header value. Derived from thread_id when omitted

Returns: Sent message details

`create_draft`

Create a draft email.

Parameters: Same as send_email

Returns: Draft details including draft_id and thread_id

`delete_drafts`

Permanently delete one or more drafts. Uses draft IDs as returned by create_draft. Note: draft IDs differ from message IDs and cannot be used with trash_emails.

Parameters:

account (required): Account ID
draft_ids (required): Array of draft IDs to delete

Returns: Count of deleted drafts

`mark_as_read`

Mark messages as read.

Parameters:

account (required): Account ID
message_ids (required): Array of message IDs

`archive_emails`

Archive messages (remove INBOX label).

Parameters:

account (required): Account ID
message_ids (required): Array of message IDs

`trash_emails`

Move messages to trash.

Parameters:

account (required): Account ID
message_ids (required): Array of message IDs

Label Operations

`add_labels`

Add labels to messages.

Parameters:

account (required): Account ID
message_ids (required): Array of message IDs
label_ids (required): Array of label IDs

`remove_labels`

Remove labels from messages.

Parameters:

account (required): Account ID
message_ids (required): Array of message IDs
label_ids (required): Array of label IDs

`create_label`

Create a new Gmail label.

Parameters:

account (required): Account ID
name (required): Label name
label_list_visibility (optional, default: "labelShow")
message_list_visibility (optional, default: "show")

`delete_label`

Delete a Gmail label.

Parameters:

account (required): Account ID
label_id (required): Label ID to delete

Troubleshooting

"Invalid grant" Error

This usually means your authorization code has expired. Authorization codes are single-use and expire after a few minutes.

Solution: Run begin_account_auth again to get a fresh OAuth URL and authorization code.

"Token has been expired or revoked"

Your refresh token is no longer valid.

Solution:

Delete the token.json file for the affected account
Run the OAuth flow again (begin_account_auth then finish_account_auth)

"Insufficient permissions"

The OAuth token doesn't have the required scopes.

Solution:

Check your Google Cloud OAuth consent screen has all required scopes
Review the current requested scopes, API enablement, and access to the specific resource.
If the grant is missing required scopes, have a human review consent and complete the separate OAuth flow again. CLI calls do not start this automatically.

Account Not Found

The specified account ID doesn't exist in accounts.json.

Solution:

Run list_accounts to see available accounts
Ensure you completed OAuth onboarding for the account
Check that the account is enabled: true in accounts.json

Rate Limiting

Gmail API has rate limits (daily quota and per-user quotas).

Solution:

Check your quota at Google Cloud Console
Implement exponential backoff in your application
Consider applying for increased quota if needed

Contributing

Contributions are welcome. Here's how:

Fork the repository
Create a feature branch (git checkout -b feature/your-feature)
Commit your changes (git commit -m 'Add your feature')
Push to the branch (git push origin feature/your-feature)
Open a Pull Request

Development Scripts

# Watch mode for development
npm run dev

# Type checking
npm run typecheck

# Build for production
npm run build

# Run the server
npm run start

License

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

Acknowledgments

Built with the Model Context Protocol SDK
Uses Google APIs Node.js Client

Links

Built by Tyler Szakacs

Quickstart TL;DR

npm install
npm run build
node dist/index.js

Then add the server to MCP config and onboard each account with begin_account_auth + finish_account_auth.

How It Works (TL;DR)

Server stores account-level credentials/tokens in local config directory
OAuth flow is handled via MCP tools
Read/search can aggregate across all enabled accounts
Gmail API calls execute per selected account

LLM Quick Copy

Use the copy button on this code block in GitHub.

Repo: gmail-multi-inbox-mcp
Goal: Multi-account Gmail MCP with built-in OAuth onboarding.
Setup:
1) npm install && npm run build
2) Add to MCP config
3) Run begin_account_auth + finish_account_auth for each inbox
Use:
- list_accounts to verify health
- read_emails/search_emails aggregated or per account
- send_email/create_draft/delete_drafts/label tools for write actions
How it works:
- Node MCP server maintains per-account token files and calls Gmail API

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
dist		dist
docs		docs
scripts		scripts
src		src
test		test
vendor/ocr		vendor/ocr
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

Gmail Multi-Inbox MCP Server

Agent CLI

Why This MCP Server?

Table of Contents

Features

Read Operations

Write Operations

Label Management

Account Management

Prerequisites

Installation

Google Cloud Setup

1. Create a Google Cloud Project

2. Enable Gmail API

3. Create OAuth 2.0 Credentials

4. OAuth Consent Screen Setup

Configuration

Add to Your MCP Settings

Custom Config Directory (Optional)

Directory Structure

accounts.json Format

Railway / SSE Deployment

OAuth Onboarding

Step 1: Start Authentication

Step 2: Complete Authentication

Usage Examples

Example 1: Read Recent Emails from All Accounts

Example 2: Search Across Multiple Accounts

Example 3: Send Email from Specific Account

Example 4: Read Only from One Account

Example 5: Manage Labels

Example 6: Delete Drafts

API Reference

Read Operations

list_accounts

read_emails

search_emails

get_email_thread

get_labels

Write Operations

send_email

create_draft

delete_drafts

mark_as_read

archive_emails

trash_emails

Label Operations

add_labels

remove_labels

create_label

delete_label

Troubleshooting

"Invalid grant" Error

"Token has been expired or revoked"

"Insufficient permissions"

Account Not Found

Rate Limiting

Contributing

Development Scripts

License

Acknowledgments

Links

Quickstart TL;DR

How It Works (TL;DR)

LLM Quick Copy

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

`list_accounts`

`read_emails`

`search_emails`

`get_email_thread`

`get_labels`

`send_email`

`create_draft`

`delete_drafts`

`mark_as_read`

`archive_emails`

`trash_emails`

`add_labels`

`remove_labels`

`create_label`

`delete_label`