# 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](https://developers.google.com/workspace/gmail/api/guides/configure-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:

```text
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:

```text
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:

```json
{
  "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:

```json
{
  "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:

```powershell
$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](LICENSE).