gmail-streamable

This MCP server exposes a Gmail-focused Model Context Protocol toolset. It presents a streamlined, LLM-friendly surface over Gmail's API, enabling inbox overview, enriched search results, thread reading, label discovery, bulk modification, and draft handling. The server emphasizes safer write flows (drafts first, explicit send) and provides human-friendly outputs that map Gmail responses into structured, actionable feedback. To begin, run the server with OAuth authentication (recommended for development), then connect your MCP client to the /mcp endpoint. Use tools like inbox_overview to establish context about the current mailbox, list_labels to discover available label IDs, and search_threads to retrieve enriched thread data. When performing changes, prefer modify_thread for batching up to 100 threads. Draft creation and sending are supported via the drafts-related capabilities and are designed to be explicit to avoid unintended mail sends.

Prerequisites:

• Node.js 18+ (or Bun if you prefer Bun-based workflows)
• A Gmail-enabled Google Cloud project with Gmail API enabled
• Basic familiarity with OAuth 2.0 flows

1. Clone the repository

git clone https://github.com/your-organization/gmail-streamable.git
cd gmail-streamable

2. Install dependencies (Node.js project example)

npm install

3. Obtain OAuth credentials

• Create a Google Cloud project and enable Gmail API
• Create OAuth 2.0 Client ID (Web application) and set redirect URIs as needed for development
• Note Client ID and Client Secret and place them in environment variables or a .env file

4. Configure environment Create a .env file or export environment variables. Example:

PORT=3000
AUTH_ENABLED=true
AUTH_STRATEGY=oauth
PROVIDER_CLIENT_ID=your-client-id.apps.googleusercontent.com
PROVIDER_CLIENT_SECRET=your-client-secret
PROVIDER_ACCOUNTS_URL=https://accounts.google.com
OAUTH_AUTHORIZATION_URL=https://accounts.google.com/o/oauth2/v2/auth
OAUTH_TOKEN_URL=https://oauth2.googleapis.com/token
OAUTH_REVOCATION_URL=https://oauth2.googleapis.com/revoke
OAUTH_SCOPES=https://www.googleapis.com/auth/gmail.readonly https://www.googleapis.com/auth/gmail.compose https://www.googleapis.com/auth/gmail.modify
OAUTH_REDIRECT_URI=alice://oauth/callback
OAUTH_REDIRECT_ALLOWLIST=alice://oauth/callback,http://127.0.0.1:3001/oauth/callback
OAUTH_EXTRA_AUTH_PARAMS=access_type=offline&prompt=consent

5. Run the server

node path/to/server.js

6. Access the MCP endpoint

• Local development: http://127.0.0.1:3000/mcp

Note: If you plan to deploy to Cloudflare Workers, follow the provider-specific setup in the README and adjust the command/endpoint accordingly.

Tips and common issues:

• If OAuth callback is not reached, verify that the redirect URI in Google Cloud Console matches the OAUTH_REDIRECT_URI and that the local server is listening on the expected port.
• For remote deployments, ensure TLS termination and proper token storage (the README mentions KV encryption; adapt env/secret management accordingly).
• Use inbox_overview first to quickly gauge mailbox state before performing searches or batch modifications.
• When using modify_thread, supply up to 100 thread IDs to minimize tool calls.
• If you see CORS or origin issues during development, ensure the development host is allowed in OAUTH_REDIRECT_ALLOWLIST and that the browser is pointed to the same origin as the MCP endpoint.
• For Cloudflare deployments, update the endpoint to the worker URL, e.g. https://<worker-name>.<account>.workers.dev/mcp, and configure VK/secret storage as described.