MCP server for Gmail with OAuth2 (personal) and service account (Workspace) support.
Setup
Choose your client, copy the config, then fill in any required environment variables.
claude mcp add gmail --env GMAIL_OAUTH_CLIENT_ID='<GMAIL_OAUTH_CLIENT_ID>' --env GMAIL_OAUTH_CLIENT_SECRET='<GMAIL_OAUTH_CLIENT_SECRET>' --env GMAIL_OAUTH_REFRESH_TOKEN='<GMAIL_OAUTH_REFRESH_TOKEN>' --env GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY='<GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY>' -- npx -y gmail-workspace-mcp-server~/.codex/config.toml
[mcp_servers.gmail]
command = "npx"
args = ["-y", "gmail-workspace-mcp-server"]
env = { GMAIL_OAUTH_CLIENT_ID = "<GMAIL_OAUTH_CLIENT_ID>", GMAIL_OAUTH_CLIENT_SECRET = "<GMAIL_OAUTH_CLIENT_SECRET>", GMAIL_OAUTH_REFRESH_TOKEN = "<GMAIL_OAUTH_REFRESH_TOKEN>", GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY = "<GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY>" }
# codex mcp add gmail --env GMAIL_OAUTH_CLIENT_ID='<GMAIL_OAUTH_CLIENT_ID>' --env GMAIL_OAUTH_CLIENT_SECRET='<GMAIL_OAUTH_CLIENT_SECRET>' --env GMAIL_OAUTH_REFRESH_TOKEN='<GMAIL_OAUTH_REFRESH_TOKEN>' --env GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY='<GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY>' -- npx -y gmail-workspace-mcp-server~/.cursor/mcp.json
{
"mcpServers": {
"gmail": {
"command": "npx",
"args": [
"-y",
"gmail-workspace-mcp-server"
],
"env": {
"GMAIL_OAUTH_CLIENT_ID": "<GMAIL_OAUTH_CLIENT_ID>",
"GMAIL_OAUTH_CLIENT_SECRET": "<GMAIL_OAUTH_CLIENT_SECRET>",
"GMAIL_OAUTH_REFRESH_TOKEN": "<GMAIL_OAUTH_REFRESH_TOKEN>",
"GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY": "<GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY>"
}
}
}
}.vscode/mcp.json
{
"servers": {
"gmail": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"gmail-workspace-mcp-server"
],
"env": {
"GMAIL_OAUTH_CLIENT_ID": "<GMAIL_OAUTH_CLIENT_ID>",
"GMAIL_OAUTH_CLIENT_SECRET": "<GMAIL_OAUTH_CLIENT_SECRET>",
"GMAIL_OAUTH_REFRESH_TOKEN": "<GMAIL_OAUTH_REFRESH_TOKEN>",
"GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY": "<GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY>"
}
}
}
}~/.gemini/settings.json
{
"mcpServers": {
"gmail": {
"command": "npx",
"args": [
"-y",
"gmail-workspace-mcp-server"
],
"env": {
"GMAIL_OAUTH_CLIENT_ID": "<GMAIL_OAUTH_CLIENT_ID>",
"GMAIL_OAUTH_CLIENT_SECRET": "<GMAIL_OAUTH_CLIENT_SECRET>",
"GMAIL_OAUTH_REFRESH_TOKEN": "<GMAIL_OAUTH_REFRESH_TOKEN>",
"GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY": "<GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY>"
}
}
}
}claude_desktop_config.json
{
"mcpServers": {
"gmail": {
"command": "npx",
"args": [
"-y",
"gmail-workspace-mcp-server"
],
"env": {
"GMAIL_OAUTH_CLIENT_ID": "<GMAIL_OAUTH_CLIENT_ID>",
"GMAIL_OAUTH_CLIENT_SECRET": "<GMAIL_OAUTH_CLIENT_SECRET>",
"GMAIL_OAUTH_REFRESH_TOKEN": "<GMAIL_OAUTH_REFRESH_TOKEN>",
"GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY": "<GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY>"
}
}
}
}.trae/mcp.json
{
"mcpServers": {
"gmail": {
"command": "npx",
"args": [
"-y",
"gmail-workspace-mcp-server"
],
"env": {
"GMAIL_OAUTH_CLIENT_ID": "<GMAIL_OAUTH_CLIENT_ID>",
"GMAIL_OAUTH_CLIENT_SECRET": "<GMAIL_OAUTH_CLIENT_SECRET>",
"GMAIL_OAUTH_REFRESH_TOKEN": "<GMAIL_OAUTH_REFRESH_TOKEN>",
"GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY": "<GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY>"
}
}
}
}Environment variables
GMAIL_OAUTH_CLIENT_IDGMAIL_OAUTH_CLIENT_SECRETGMAIL_OAUTH_REFRESH_TOKENGMAIL_SERVICE_ACCOUNT_PRIVATE_KEY
Replace the placeholders with your own credentials and keep them out of version control.