Gmail

This MCP server exposes Gmail tools over a streamable HTTP transport to let your AI assistants read, search, organize, and draft emails across connected Gmail accounts. It supports multiple Gmail accounts per user, handles OAuth securely, and keeps tokens encrypted for safe long‑term use.

How to use

You connect your Gmail accounts to the MCP server and then issue tool requests from your MCP client. The server exposes a MCP endpoint you can talk to, typically at the /mcp path, and a Gmail OAuth flow you start from /oauth/start. You can target a specific connected account by providing an email address with your tool request; if you omit the email, the server uses the default account.

Once connected, you can perform actions such as checking status, listing accounts, searching messages, reading threads, archiving, labeling, drafting, and more. The system supports multiple Gmail accounts per user, with a default account designated for convenience. All actions respect Gmail scopes like readonly access, modification privileges, and draft composition.

How to install

Prerequisites you need before installation:

• Node.js 20.x or newer
• A Google Cloud project with Gmail API enabled
• OAuth 2.0 credentials for a Web application

1. Clone the project and enter the directory.

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

Install and run the server

Install dependencies and build the project, then start the server.

git clone https://github.com/shcallaway/gmail-mcp-server.git
cd gmail-mcp-server
npm install
npm run build

Set up secrets and environment variables

Generate secrets and configure OAuth credentials in an environment file.

# Generate secrets
./bin/generate-secrets.sh

# Or generate with npm helper
npm run bin:generate-secrets

Run in production or development

Start the server in production mode or with development hot reload.

# Production build and start
npm run build
npm start

# Development with hot reload
npm run dev

Docker deployment (optional)

If you prefer containerized deployment, use the provided Docker commands to manage the server lifecycle.

npm run docker:up       # Start the server
npm run docker:down     # Stop the server
npm run docker:logs     # Tail logs
npm run docker:restart  # Restart container
npm run docker:build    # Rebuild image

OAuth and Gmail setup reminders

Complete Google Cloud setup and configure OAuth credentials as shown in the guidance: create a project, enable Gmail API, configure OAuth consent screen with appropriate scopes, and create OAuth client credentials with a redirect URI of http://localhost:3000/oauth/callback.

Client connection and health endpoints

The server exposes a MCP endpoint for protocol calls and a health check to verify readiness. You can initiate Gmail OAuth through the /oauth/start path and handle the callback at /oauth/callback.

Notes on multi-account and scopes

You can connect several Gmail accounts. Each account may require different OAuth scopes, and you can designate which account is used by default when making requests.

Available tools

gmail.status

Check connection status and list all connected Gmail accounts

gmail.authorize

Initiate OAuth flow to connect Gmail accounts

gmail.listAccounts

List all connected Gmail accounts

gmail.setDefaultAccount

Set which Gmail account is used by default

gmail.removeAccount

Disconnect a Gmail account

gmail.searchMessages

Search messages using Gmail query syntax

gmail.getMessage

Retrieve a single message by ID

gmail.listThreads

List conversation threads

gmail.getThread

Get all messages in a thread

gmail.getAttachmentMetadata

Get attachment details for a message

gmail.listLabels

List all mailbox labels with counts

gmail.getLabelInfo

Get details about a label

gmail.addLabels

Add labels to messages or threads

gmail.removeLabels

Remove labels from messages or threads

gmail.createLabel

Create a custom label

gmail.archiveMessages

Archive messages or threads (thread-aware by default)

gmail.unarchiveMessages

Unarchive messages or threads (thread-aware by default)

gmail.markAsRead

Mark messages as read

gmail.markAsUnread

Mark messages as unread

gmail.starMessages

Add stars to messages

gmail.unstarMessages

Remove stars from messages

gmail.createDraft

Create a new draft

gmail.listDrafts

List all drafts

gmail.getDraft

Get draft content

gmail.updateDraft

Update an existing draft

gmail.deleteDraft

Delete a draft