gmail

This Gmail MCP Server exposes Gmail inbox tools via Streamable HTTP transport, enabling MCP-compatible clients (like Claude Code) to connect multiple Gmail accounts and perform a wide range of actions. After starting the server, you can authenticate via two-layer OAuth: MCP-level JWT authentication for MCP clients and Google OAuth for Gmail access. The server provides tools organized by capability, including authorization and status checks, account management, reading email, label operations, and message modifications. Use the provided commands or MCP tools to search messages, read threads, manage labels, archive or star items, and draft messages. The architecture routes client requests through a Fastify HTTP layer to the Gmail API, with a SQLite-backed encrypted token store to securely persist refresh tokens. This setup supports multi-account usage and per-account operations, so you can switch default accounts or target specific emails as needed.

Prerequisites: a machine with Node.js and npm installed, Git, and network access to Google OAuth endpoints. Ensure you have Docker available if you prefer containerized deployment. Steps:

1. Install dependencies:
   • git clone https://github.com/yourusername/gmail-mcp.git
   • cd gmail-mcp
   • npm install
2. Configure Google OAuth:
   • Go to Google Cloud Console, create a project, enable Gmail API, and create OAuth 2.0 credentials (Web application).
   • Set the authorized redirect URI to http://localhost:3000/oauth/callback.
   • Copy the Client ID and Client Secret and store them in your environment as GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET.
3. Create and populate environment variables:
   • Create a .env file or set these in your environment: PORT=3000 BASE_URL=https://your-public-url GOOGLE_CLIENT_ID=your-client-id GOOGLE_CLIENT_SECRET=your-client-secret OAUTH_REDIRECT_URI=https://your-public-url/oauth/callback TOKEN_ENCRYPTION_KEY=base64-encoded-32-byte-key JWT_SECRET=your-mcp-jwt-secret DB_URL=./data/gmail-mcp.db ALLOWED_ORIGINS=* (or a comma-separated list)
4. Build and run:
   • npm run build
   • npm run start
5. Verify:
   • Open http://localhost:3000 to confirm the server is running and reachable.

Tips and considerations:

• The token store uses AES-256-GCM encryption in SQLite for secure refresh token storage.
• Docker deployment is supported via docker-compose; you can adapt the environment variables in your compose file.
• To connect multiple Gmail accounts, use the Gmail authorize flow (gmail.authorize) and switch accounts with gmail.setDefaultAccount as needed.
• Ensure proper OAuth scopes are requested (gmail.readonly, gmail.labels, gmail.modify, gmail.compose) according to the features you intend to use.
• If you encounter connection issues, check environment variable values, network access to Google APIs, and that the OAuth redirect URI matches exactly.
• Logs can help diagnose issues; for containerized setups, use docker compose logs -f to tail logs.