Gmail Streamable

iceener10stars

MCP Server for interacting with Gmail API. Written in TypeScript, Node and Hono.dev

1# Gmail Streamable

README.mdMCP server

Transport: stdio
Status: Local

Power your agent

Add this server

Install from the publisher. Not a PlugMCP endpoint.

Run on PlugMCP

Host a copy with our keys and logs.

No packaged release in the registry yet. Follow the repository README.

RepositoryPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
License: MIT
Last checked: 2026-10-27

Stars: 10
Tools: —
Uptime: —

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

How do I install Gmail Streamable?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Gmail Streamable need an API key?

No required environment variable is listed on this record.

What transport does Gmail Streamable use?

Gmail Streamable runs locally over stdio.

When was Gmail Streamable last checked?

Last checked 2026-10-27. MCP Server for interacting with Gmail API. Written in TypeScript, Node and Hono.dev

From the publisher

Documentation

Gmail MCP Server

This server is a remote Model Context Protocol (MCP) server for Gmail. A model can use it to read, search, label and draft email, and to send drafts. The server runs on Cloudflare Workers and on Bun. It uses the MCP server template 2.1 and the official MCP TypeScript SDK 2.3.0.

The server URL is the deployed Worker's MCP_PUBLIC_URL, for example https://gmail-mcp.<subdomain>.workers.dev/mcp.

The server uses protocol version 2026-07-28. It also accepts clients that use the 2025 protocol versions.

[!WARNING] You connect this server to your MCP client at your own risk. A model can make mistakes. Examine what the tools do, and examine changes in Gmail. The server can send email that is in a draft.

Tools

Tool	Function
`get_profile`	Shows the email address of the connected Gmail account.
`inbox_overview`	Shows counts (unread, inbox, sent, starred, important) and the newest unread and starred threads for a period. The default period is 7 days.
`list_labels`	Lists the labels with their IDs, types and counts.
`modify_thread`	Adds and removes labels on up to 100 threads. Actions: archive, unarchive, markRead, markUnread, star, unstar, trash, untrash, spam, unspam.
`search_threads`	Finds threads with a Gmail query or label IDs. The newest message sets the order. The result has the subject, the sender, the dates, the labels and a web link.
`get_thread`	Shows a thread and its messages. The `format` argument controls the bodies.
`get_message`	Shows one message.
`create_draft`	Makes a draft. For a reply, give the `threadId`.
`update_draft`	Replaces the message in a draft.
`send_draft`	Sends a draft. It can replace the message first.

The server writes to Gmail only through drafts and labels. It sends email only with send_draft.

Connect a client

Use the server URL and the Streamable HTTP transport. The client signs you in with Google the first time.

Client	Procedure
Claude	In Settings → Connectors, add a custom connector with the server URL.
Claude Code	Run `claude mcp add --transport http gmail <server URL>`.
MCP Inspector	Run `bun run inspector`. Select Streamable HTTP. Enter the server URL.

Alice and Wonderlands use the same URL.

Authentication

The server is its own OAuth authorization server, in front of Google's OAuth. MCP clients do not receive Google tokens.

The client registers at /register and signs the user in at /authorize. The client must use PKCE S256.
The server sends the user to Google. Google asks for the three Gmail scopes.
Google returns the user to the server's /oauth/callback. The server keeps the Google tokens, encrypted.
The client gets a code, and exchanges the code at /token for an access token and a refresh token. These tokens are opaque and have meaning only for this server.
On each MCP request, the server finds the Google token for the access token. If the Google token expires in less than one minute, the server refreshes it first. The tools use the Google token. They do not see the client's token.

For the complete flow, the storage and the redirect rules, refer to docs/oauth.md.

Configuration

The deployment settings are in wrangler.production.jsonc (Workers; gitignored, with wrangler.production.example.jsonc as its shape) or .env (Bun). .env.example describes all variables.

Variable	Production value	Function
`MCP_PUBLIC_URL`	`https://gmail-mcp.<subdomain>.workers.dev/mcp`	The public URL of the MCP endpoint. It is also the resource that tokens are issued for.
`MCP_ALLOWED_HOSTS`	`gmail-mcp.<subdomain>.workers.dev`	The `Host` headers that the server accepts.
`MCP_ALLOWED_ORIGIN_HOSTNAMES`	The server host, `claude.ai`, `claude.com`, and the hosts of the operator's own browser clients	The browser origins that the server accepts.
`AUTH_MODE`	`oauth`	The server checks the tokens that it issued.
`OAUTH_ISSUER_URL`, `OAUTH_AUTHORIZATION_URL`, `OAUTH_TOKEN_URL`, `OAUTH_REGISTRATION_URL`	This server's origin, `/authorize`, `/token` and `/register`	The authorization server that clients use. The server does not start if they name another server.
`OAUTH_SCOPES`	The three Gmail scopes	The scopes that every MCP request must have.
`PROXY_REDIRECT_ALLOWLIST`	Alice, Claude and Wonderlands callbacks	The client redirect URIs that the proxy accepts, in addition to native loopback URIs.
`MCP_MAX_REQUEST_BYTES`	`1048576`	The largest MCP request body.
`MCP_LEGACY_MODE`	`stateless`	The server also accepts 2025-era clients.

Secrets:

Secret	Function
`PROVIDER_CLIENT_ID`	The server's Google OAuth client ID.
`PROVIDER_CLIENT_SECRET`	The server's Google OAuth client secret.
`RS_TOKENS_ENC_KEY`	32 random bytes, base64url. The key encrypts the stored tokens. If you change it, all users must sign in again.

The Google endpoints, the Gmail scopes and the offline-access parameters are constants in src/services/google-oauth.ts. For the setup at Google and at Cloudflare, refer to docs/deploy.md.

Development

Requirements: Bun 1.4 or later, and Node.js 22.18 or later.

Install the dependencies:
```
bun install
```
Copy .env.example to .env. Set PROVIDER_CLIENT_ID, PROVIDER_CLIENT_SECRET and RS_TOKENS_ENC_KEY. At Google, allow the redirect URI http://127.0.0.1:3000/oauth/callback.
Start the server:
```
bun run dev
```
The server URL is http://127.0.0.1:3000/mcp. To use the Cloudflare local runtime, run bun run dev:worker (port 8787). Put its secrets in .dev.vars.
Before you commit, run the checks:
```
bun run check
bun run test:smoke
```

bun run check does the type check, the lint check and the tests. bun run test:smoke starts the real server on Bun and on workerd. It signs in through a Google stand-in on loopback and calls the tools. No test uses the network.

Script	Function
`bun run dev`	Starts the server on Bun.
`bun run dev:worker`	Starts the server in the Cloudflare local runtime.
`bun run check`	Type check, lint check, tests, and the check of the generated Worker types.
`bun run test:smoke`	Smoke tests on Bun and on workerd.
`bun run deploy`	Deploys with the gitignored `wrangler.production.jsonc` (`wrangler deploy --config wrangler.production.jsonc`).
`bun run types:worker`	Makes the Worker types again after a change to `wrangler.jsonc`.

Project structure

src/
  server.ts       Identity, Runtime, Deps, and the hooks that connect the OAuth proxy
  settings.ts     The Google client, the encryption key, the redirect allowlist
  tools/          One file for each tool; shared/ has schemas and helpers
  services/       The Gmail API client, and google-oauth.ts: Google as the OAuth provider
  oauth/          The OAuth proxy. It is the same for every provider (docs/oauth.md)
  platform/       Template code. Do not change it
  bun.ts          Entry point for Bun: file storage
  worker.ts       Entry point for Workers: KV and the NativeOAuthAuthority Durable Object
tests/            Tests for the tools, the proxy and the platform; fixtures from before 1.1.0
scripts/          Smoke tests and the Google stand-in

For the template's concepts (the request path, defineTool, the error policy, the configuration checks), refer to the template documentation.

License

MIT

Gmail Streamable

iceener10stars

MCP Server for interacting with Gmail API. Written in TypeScript, Node and Hono.dev

Communication

Install Run on PlugMCP

GitHub

Run on PlugMCP

1# Gmail Streamable

README.mdMCP server

Transport: stdio
Status: Local

Power your agent

Add this server

Install from the publisher. Not a PlugMCP endpoint.

Run on PlugMCP

Host a copy with our keys and logs.

No packaged release in the registry yet. Follow the repository README.

RepositoryPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
License: MIT
Last checked: 2026-10-27

Stars: 10
Tools: —
Uptime: —

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

How do I install Gmail Streamable?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Gmail Streamable need an API key?

No required environment variable is listed on this record.

What transport does Gmail Streamable use?

Gmail Streamable runs locally over stdio.

When was Gmail Streamable last checked?

Last checked 2026-10-27. MCP Server for interacting with Gmail API. Written in TypeScript, Node and Hono.dev

From the publisher

Documentation

Gmail MCP Server

The server URL is the deployed Worker's MCP_PUBLIC_URL, for example https://gmail-mcp.<subdomain>.workers.dev/mcp.

The server uses protocol version 2026-07-28. It also accepts clients that use the 2025 protocol versions.

[!WARNING] You connect this server to your MCP client at your own risk. A model can make mistakes. Examine what the tools do, and examine changes in Gmail. The server can send email that is in a draft.

Tools

Tool	Function
`get_profile`	Shows the email address of the connected Gmail account.
`inbox_overview`	Shows counts (unread, inbox, sent, starred, important) and the newest unread and starred threads for a period. The default period is 7 days.
`list_labels`	Lists the labels with their IDs, types and counts.
`modify_thread`	Adds and removes labels on up to 100 threads. Actions: archive, unarchive, markRead, markUnread, star, unstar, trash, untrash, spam, unspam.
`search_threads`	Finds threads with a Gmail query or label IDs. The newest message sets the order. The result has the subject, the sender, the dates, the labels and a web link.
`get_thread`	Shows a thread and its messages. The `format` argument controls the bodies.
`get_message`	Shows one message.
`create_draft`	Makes a draft. For a reply, give the `threadId`.
`update_draft`	Replaces the message in a draft.
`send_draft`	Sends a draft. It can replace the message first.

The server writes to Gmail only through drafts and labels. It sends email only with send_draft.

Connect a client

Use the server URL and the Streamable HTTP transport. The client signs you in with Google the first time.

Client	Procedure
Claude	In Settings → Connectors, add a custom connector with the server URL.
Claude Code	Run `claude mcp add --transport http gmail <server URL>`.
MCP Inspector	Run `bun run inspector`. Select Streamable HTTP. Enter the server URL.

Alice and Wonderlands use the same URL.

Authentication

The server is its own OAuth authorization server, in front of Google's OAuth. MCP clients do not receive Google tokens.

The client registers at /register and signs the user in at /authorize. The client must use PKCE S256.
The server sends the user to Google. Google asks for the three Gmail scopes.
Google returns the user to the server's /oauth/callback. The server keeps the Google tokens, encrypted.
The client gets a code, and exchanges the code at /token for an access token and a refresh token. These tokens are opaque and have meaning only for this server.
On each MCP request, the server finds the Google token for the access token. If the Google token expires in less than one minute, the server refreshes it first. The tools use the Google token. They do not see the client's token.

For the complete flow, the storage and the redirect rules, refer to docs/oauth.md.

Configuration

The deployment settings are in wrangler.production.jsonc (Workers; gitignored, with wrangler.production.example.jsonc as its shape) or .env (Bun). .env.example describes all variables.

Variable	Production value	Function
`MCP_PUBLIC_URL`	`https://gmail-mcp.<subdomain>.workers.dev/mcp`	The public URL of the MCP endpoint. It is also the resource that tokens are issued for.
`MCP_ALLOWED_HOSTS`	`gmail-mcp.<subdomain>.workers.dev`	The `Host` headers that the server accepts.
`MCP_ALLOWED_ORIGIN_HOSTNAMES`	The server host, `claude.ai`, `claude.com`, and the hosts of the operator's own browser clients	The browser origins that the server accepts.
`AUTH_MODE`	`oauth`	The server checks the tokens that it issued.
`OAUTH_ISSUER_URL`, `OAUTH_AUTHORIZATION_URL`, `OAUTH_TOKEN_URL`, `OAUTH_REGISTRATION_URL`	This server's origin, `/authorize`, `/token` and `/register`	The authorization server that clients use. The server does not start if they name another server.
`OAUTH_SCOPES`	The three Gmail scopes	The scopes that every MCP request must have.
`PROXY_REDIRECT_ALLOWLIST`	Alice, Claude and Wonderlands callbacks	The client redirect URIs that the proxy accepts, in addition to native loopback URIs.
`MCP_MAX_REQUEST_BYTES`	`1048576`	The largest MCP request body.
`MCP_LEGACY_MODE`	`stateless`	The server also accepts 2025-era clients.

Secrets:

Secret	Function
`PROVIDER_CLIENT_ID`	The server's Google OAuth client ID.
`PROVIDER_CLIENT_SECRET`	The server's Google OAuth client secret.
`RS_TOKENS_ENC_KEY`	32 random bytes, base64url. The key encrypts the stored tokens. If you change it, all users must sign in again.

The Google endpoints, the Gmail scopes and the offline-access parameters are constants in src/services/google-oauth.ts. For the setup at Google and at Cloudflare, refer to docs/deploy.md.

Development

Requirements: Bun 1.4 or later, and Node.js 22.18 or later.

Install the dependencies:
```
bun install
```
Copy .env.example to .env. Set PROVIDER_CLIENT_ID, PROVIDER_CLIENT_SECRET and RS_TOKENS_ENC_KEY. At Google, allow the redirect URI http://127.0.0.1:3000/oauth/callback.
Start the server:
```
bun run dev
```
The server URL is http://127.0.0.1:3000/mcp. To use the Cloudflare local runtime, run bun run dev:worker (port 8787). Put its secrets in .dev.vars.
Before you commit, run the checks:
```
bun run check
bun run test:smoke
```

Script	Function
`bun run dev`	Starts the server on Bun.
`bun run dev:worker`	Starts the server in the Cloudflare local runtime.
`bun run check`	Type check, lint check, tests, and the check of the generated Worker types.
`bun run test:smoke`	Smoke tests on Bun and on workerd.
`bun run deploy`	Deploys with the gitignored `wrangler.production.jsonc` (`wrangler deploy --config wrangler.production.jsonc`).
`bun run types:worker`	Makes the Worker types again after a change to `wrangler.jsonc`.

Project structure

src/
  server.ts       Identity, Runtime, Deps, and the hooks that connect the OAuth proxy
  settings.ts     The Google client, the encryption key, the redirect allowlist
  tools/          One file for each tool; shared/ has schemas and helpers
  services/       The Gmail API client, and google-oauth.ts: Google as the OAuth provider
  oauth/          The OAuth proxy. It is the same for every provider (docs/oauth.md)
  platform/       Template code. Do not change it
  bun.ts          Entry point for Bun: file storage
  worker.ts       Entry point for Workers: KV and the NativeOAuthAuthority Durable Object
tests/            Tests for the tools, the proxy and the platform; fixtures from before 1.1.0
scripts/          Smoke tests and the Google stand-in

For the template's concepts (the request path, defineTool, the error policy, the configuration checks), refer to the template documentation.

License

MIT