Gmail Local MCP

Local stdio MCP server that mirrors the public Gmail MCP server tool surface while calling the Gmail REST API directly. It is intended as a temporary stand-in for https://gmailmcp.googleapis.com/mcp/v1.

Setup

1. Follow Google's official Configure the Gmail MCP server guide to provision a Google Cloud project, enable the Gmail API and Gmail MCP API, configure the OAuth consent screen, and create a Google OAuth desktop client.

2. Copy config.sample.json to config.json.

3. Fill in oauth.clientId and oauth.clientSecret with the OAuth client values from the official provisioning flow, then set the official Gmail MCP scopes:

   • https://www.googleapis.com/auth/gmail.readonly

   • https://www.googleapis.com/auth/gmail.compose

4. Run npm install and npm run build.

config.json and .gmail-token.json are gitignored. On startup the server refreshes saved tokens when possible. If no token is present, or the token cannot be refreshed, it starts a localhost OAuth callback and opens the Google login page in your browser.

OAuth redirect URI

The local OAuth callback URL is:

http://127.0.0.1:<redirectPort>/oauth2callback

If you use a Google OAuth Web application client, set redirectPort in config.json to a fixed port and add that exact URL to the client's Authorized redirect URIs. For example, with "redirectPort": 3000, add:

http://127.0.0.1:3000/oauth2callback

The default sample uses "redirectPort": 0, which lets the OS choose an available port. That is convenient for a Google OAuth Desktop app client, but it is not suitable for a Web application client because the redirect URI must be registered exactly.

Official remote Gmail MCP configuration

If you want to use Google's hosted Gmail MCP server instead of this local stdio stand-in, use the official server URL and OAuth configuration from Google's provisioning guide:

{
  "mcpServers": {
    "gmail": {
      "httpUrl": "https://gmailmcp.googleapis.com/mcp/v1",
      "oauth": {
        "enabled": true,
        "clientId": "OAUTH_CLIENT_ID",
        "clientSecret": "OAUTH_CLIENT_SECRET",
        "scopes": [
          "https://www.googleapis.com/auth/gmail.readonly",
          "https://www.googleapis.com/auth/gmail.compose"
        ]
      }
    }
  }
}

Replace OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET with the OAuth client values you created in Google Cloud.

MCP client configuration

Use stdio transport and point your client at the built server. Replace /path/to/gmail-local-mcp with the directory where you cloned or copied this repo.

GitHub Copilot CLI

Add this server to your Copilot CLI MCP server configuration:

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": [
        "/path/to/gmail-local-mcp/dist/src/index.js",
        "--config",
        "/path/to/gmail-local-mcp/config.json"
      ]
    }
  }
}

On Windows, use escaped backslashes in JSON paths, for example C:\\path\\to\\gmail-local-mcp\\dist\\src\\index.js.

For development, use npm run dev -- --config config.json.

Tools

The server exposes the same 10 tool names as the public Gmail MCP server:

create_draft, list_drafts, get_thread, search_threads, label_thread, unlabel_thread, list_labels, label_message, unlabel_message, and create_label.

Non-interactive testing

You can provide a short-lived access token without writing it to disk. In this mode, config.json is optional:

$env:GMAIL_ACCESS_TOKEN = "ya29..."
npm run e2e

The e2e script only calls read/list tools so it can run with the official Gmail MCP scope set.

License

This project is licensed under the MIT License.