gmail-mcp
Allows interacting with Gmail to list, read, and search emails, and manage labels.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@gmail-mcp list my 5 most recent emails"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Gmail MCP Server
Gmail MCP Server is a Node.js/TypeScript-based MCP stdio server that allows OpenClaw to read Gmail emails via the Model Context Protocol.
Features
Uses Gmail API OAuth 2.0 authorization with read-only scope:
https://www.googleapis.com/auth/gmail.readonlylist_emails: Lists inbox emails, supportingmaxResultsand Gmailqueryfilteringget_email: Reads details of a single email viamessageIdsearch_emails: Searches for emails using Gmail search syntaxlist_labels: Lists all Gmail labels/foldersSupports MCP stdio transport for OpenClaw integration
Related MCP server: gmail-mcp
Requirements
Node.js 18 or higher
npm
A Google account with access to the Gmail API
Installation
npm install
npm run buildCreate OAuth Credentials in Google Cloud Console
Open the Google Cloud Console.
Create or select a project.
Go to
APIs & Services->Library, search for and enableGmail API.Go to
APIs & Services->OAuth consent screen.Select the user type. For personal use, usually select
External.Fill in the application name, user support email, and developer contact email.
In the Scopes step, add the Gmail read-only permission:
https://www.googleapis.com/auth/gmail.readonly.If the app is in Testing status, add your Gmail account to Test users.
Go to
APIs & Services->Credentials.Click
Create Credentials->OAuth client ID.Select
Desktop appas the Application type.Download the JSON file after creation.
Place credentials.json
Create the configuration directory and save the downloaded OAuth JSON as:
mkdir -p ~/.gmail-mcp
chmod 700 ~/.gmail-mcp
cp /path/to/downloaded/client_secret.json ~/.gmail-mcp/credentials.json
chmod 600 ~/.gmail-mcp/credentials.jsonThe final path must be:
~/.gmail-mcp/credentials.jsonRun Authorization Flow
npm run authThe script will:
Start a temporary local OAuth callback service
Open the browser for Google authorization
Save the token to
~/.gmail-mcp/token.jsonafter authorization is complete
If the browser does not open automatically, the terminal will print the authorization URL; copy it to your browser manually.
Start MCP Server
npm run startstart uses stdio transport and is typically started by OpenClaw as an MCP server subprocess; it does not need to be run manually for long periods.
OpenClaw MCP Configuration Example
Point the command to the built entry point of this project:
{
"mcpServers": {
"gmail": {
"command": "node",
"args": ["/Volumes/DevDisk/symbol/gmailMCP/dist/src/index.js"]
}
}
}You can also start it using npm within the project directory:
{
"mcpServers": {
"gmail": {
"command": "npm",
"args": ["run", "start"],
"cwd": "/Volumes/DevDisk/symbol/gmailMCP"
}
}
}Tools Parameter Description
list_emails
List inbox emails.
{
"maxResults": 10,
"query": "from:example@gmail.com newer_than:7d"
}maxResults: Optional, default10, maximum50query: Optional, Gmail search syntax, restricted to INBOX queries
get_email
Read details of a single email.
{
"messageId": "18f..."
}Returned fields include sender, recipient, subject, date, labels, body text, HTML body, and attachment metadata.
search_emails
Search Gmail emails.
{
"query": "subject:invoice has:attachment newer_than:30d",
"maxResults": 10
}query: Required, supports Gmail search syntaxmaxResults: Optional, default10, maximum50
list_labels
List all labels/folders.
{}File Locations
OAuth credentials:
~/.gmail-mcp/credentials.jsonOAuth token:
~/.gmail-mcp/token.jsonMCP server entry point:
dist/src/index.js
FAQ
Missing Gmail OAuth credentials
Confirm that you have downloaded the Google OAuth client JSON and saved it to:
~/.gmail-mcp/credentials.jsonMissing Gmail OAuth token
Run the following first:
npm run authaccess_denied or app not verified
If the OAuth consent screen is still in Testing status, you need to add the current Gmail account to Test users.
invalid_grant
Delete the old token and re-authorize:
rm ~/.gmail-mcp/token.json
npm run authAvailable Tools
4 toolsget_emailA
Read one Gmail message by messageId.
Inputs: messageId (required).
list_emailsB
List Gmail inbox messages. Supports maxResults and Gmail query filters.
Inputs: maxResults, query.
list_labelsA
List all Gmail labels and folders.
Inputs: no named parameters.
search_emailsA
Search Gmail messages with Gmail search syntax.
Inputs: query (required), maxResults.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool targets a distinct operation: reading a single email by ID, listing inbox messages, searching with Gmail syntax, and listing labels. There is no overlap in functionality.
All tool names follow the consistent verb_noun pattern in snake_case: get_email, list_emails, list_labels, search_emails.
With 4 tools, the set is concise and scoped to basic read and list operations. While it covers common use cases, it could be expanded with write operations, but the count is reasonable for a focused subset.
The tool surface lacks write operations such as sending, deleting, or modifying emails and labels. Users cannot perform actions beyond reading and listing, which is a significant gap for comprehensive Gmail management.
Maintenance
Related MCP Connectors
Give AI agents their own email inboxes: list, read and send mail via scoped, revocable OAuth grants.
Email for AI agents: read, search and send from your Gmail, Outlook, Yahoo, iCloud or IMAP inbox.
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Manage Gmail end-to-end: search, read, send, draft, label, and organize threads. Automate workflow…
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides comprehensive Gmail integration with LLM processing capabilities, allowing users to read, search, filter emails and handle attachments through the Model Context Protocol.25 npm2MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that enables full management of Gmail accounts, including messages, threads, labels, and drafts. It leverages the Gmail API to allow searching, sending, and organizing emails via secure OAuth2 authentication.MIT
- FlicenseNot gradedqualityDmaintenanceProvides access to Gmail functionality through the Model Context Protocol, allowing LLMs like Claude to interact with your email.2-
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to manage Gmail through natural language, including search, read, send, label, and draft operations via the Model Context Protocol.-