Google Postmaster MCP Server

Vibe coded: This project is almost fully AI generated (written with Claude). It was built quickly and has had limited manual review and no automated tests, so read the code before trusting it with anything important.

It is also not actively maintained. If you find a bug, feel free to open a PR or reach out at postmaster-mcp@jimvanduijsen.nl.

This is a stdio MCP server for the Gmail Postmaster Tools API v2. It exposes tools for listing registered domains, reading domain metadata, checking compliance status, and querying Postmaster traffic metrics.

Google requires OAuth 2.0 for Postmaster Tools API requests. Use a Google account that has access to the domains in Postmaster Tools.

Tools

• postmaster_list_domains
• postmaster_get_domain
• postmaster_get_compliance_status
• postmaster_query_domain_stats
• postmaster_batch_query_domain_stats
• postmaster_metric_reference

Setup

1. Enable the Postmaster Tools API in Google Cloud.
2. Configure Google Auth Platform for OAuth:
   • Go to Google Cloud Console > Google Auth Platform.
   • Set the app audience/user type to External.
   • Keep the publishing status in Testing while you are setting this up.
   • Add your own Google account email under Test users.
3. Add the Postmaster scopes under Data Access:

https://www.googleapis.com/auth/postmaster.domain
https://www.googleapis.com/auth/postmaster.traffic.readonly

The broad https://www.googleapis.com/auth/postmaster scope also works.

4. Create an OAuth client with application type Desktop app. Copy the client ID and client secret into .env:

cp .env.example .env

POSTMASTER_CLIENT_ID=your-client-id
POSTMASTER_CLIENT_SECRET=your-client-secret
POSTMASTER_REFRESH_TOKEN=

Requires Node.js 20 or newer and pnpm. Install and build:

pnpm install
pnpm build

Create a refresh token:

pnpm oauth

The OAuth helper automatically loads .env from the current directory and uses an available loopback redirect port by default. After the browser authorization succeeds, it saves POSTMASTER_REFRESH_TOKEN back into .env.

If you instead create a Web application OAuth client, set POSTMASTER_OAUTH_REDIRECT_URI to a fixed loopback URL and add that exact URL as an authorized redirect URI in Google Cloud.

Note: while the OAuth app is in Testing mode, only test users can authorize it. Google can expire refresh tokens for Testing apps after 7 days. If API calls start failing later, rerun pnpm oauth or move the app to production after completing Google's requirements.

Claude Desktop

On macOS, Claude Desktop reads:

~/Library/Application Support/Claude/claude_desktop_config.json

Add this MCP server entry. Replace /absolute/path/to/postmaster with the path to this project:

{
  "mcpServers": {
    "google-postmaster": {
      "command": "node",
      "args": ["/absolute/path/to/postmaster/dist/src/index.js"],
      "env": {
        "POSTMASTER_DOTENV_FILE": "/absolute/path/to/postmaster/.env"
      }
    }
  }
}

Fully quit and restart Claude Desktop after changing this file.

Claude Code

From this project directory, add the server to Claude Code local config:

claude mcp add-json --scope local google-postmaster '{"command":"node","args":["/absolute/path/to/postmaster/dist/src/index.js"],"env":{"POSTMASTER_DOTENV_FILE":"/absolute/path/to/postmaster/.env"}}'

Check the connection:

claude mcp get google-postmaster

Expected status:

Status: ✓ Connected

Other MCP Clients

Use the built server with any stdio MCP client. Prefer pointing the server at the .env file:

{
  "mcpServers": {
    "google-postmaster": {
      "command": "node",
      "args": ["/absolute/path/to/postmaster/dist/src/index.js"],
      "env": {
        "POSTMASTER_DOTENV_FILE": "/absolute/path/to/postmaster/.env"
      }
    }
  }
}

For quick testing, you can use a short-lived token instead:

{
  "env": {
    "POSTMASTER_ACCESS_TOKEN": "ya29..."
  }
}

Example Tool Inputs

Query spam rate for one date range:

{
  "domain": "example.com",
  "dateRanges": [
    {
      "start": "2026-05-01",
      "end": "2026-05-07"
    }
  ],
  "metrics": [
    {
      "name": "spam_rate",
      "standardMetric": "SPAM_RATE"
    }
  ],
  "aggregationGranularity": "DAILY"
}

Query DKIM authentication success:

{
  "domain": "example.com",
  "dates": ["2026-05-01"],
  "metrics": [
    {
      "name": "dkim_auth_success",
      "standardMetric": "AUTH_SUCCESS_RATE",
      "filter": "auth_type = \"dkim\""
    }
  ]
}

Credential Options

The server checks credentials in this order:

1. POSTMASTER_ACCESS_TOKEN or GOOGLE_ACCESS_TOKEN
2. POSTMASTER_CLIENT_ID, POSTMASTER_CLIENT_SECRET, and POSTMASTER_REFRESH_TOKEN
3. POSTMASTER_OAUTH_CREDENTIALS, containing authorized user JSON
4. POSTMASTER_OAUTH_CREDENTIALS_FILE, pointing to authorized user JSON

GOOGLE_* variants are accepted for the client ID, client secret, refresh token, and OAuth credentials file. The server loads .env automatically from the current directory. Set POSTMASTER_DOTENV_FILE=/absolute/path/to/.env when the MCP client starts the server from another working directory.

API Notes

The server targets https://gmailpostmastertools.googleapis.com/v2. By default, postmaster_query_domain_stats queries SPAM_RATE if no metrics are supplied. Use postmaster_metric_reference to see supported standard metrics and required filter syntax.

Notes

This server uses a pre-release (alpha) version of the MCP TypeScript SDK, so breaking changes upstream are possible.

References

• Postmaster Tools API setup
• Configure OAuth consent and scopes
• Manage Google Auth Platform app audience