ShijoeBytesBric/gmail-mcp

Gmail MCP Server

A Model Context Protocol (MCP) server for Gmail draft management. Allows AI assistants to create, read, update, delete, and send Gmail drafts through a secure HTTP interface.

Features

• Create, list, get, update, delete, and send Gmail drafts
• OAuth 2.0 authentication with automatic token refresh
• HTTP transport for MCP protocol
• TypeScript implementation with full type safety

Quick Start

1. Install Dependencies

npm install

2. Set Up Gmail API Credentials

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Gmail API
4. Create OAuth 2.0 credentials (Desktop Application type)
5. Download the credentials file and save it as credentials.json in the project root

3. Generate Authentication Token

Run the server once to trigger the OAuth flow:

npm run build
npm start

This will:

• Open your browser for Gmail authentication
• Generate a token.json file with your access and refresh tokens
• Store the tokens securely for future use

4. Configure Environment (Optional)

Copy .env.example to .env and customize if needed:

PORT=3000
HOST=localhost
CREDENTIALS_PATH=./credentials.json
TOKEN_PATH=./token.json
LOG_LEVEL=info

5. Start the Server

npm start

The server will run on http://localhost:3000

Client Configuration

To connect MCP clients to this server, use the following configuration:

{
  "mcpServers": {
    "gmail": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Available Tools

Credential Management

Initial Setup

1. credentials.json: OAuth 2.0 client credentials from Google Cloud Console

   • Contains client_id, client_secret, and redirect_uris
   • Required for authentication flow
   • See credentials.json.example for the expected format

2. token.json: Generated after first authentication

   • Contains access_token, refresh_token, and expiry information
   • Automatically created and managed by the server
   • See token.json.example for the expected format

Token Refresh

• Access tokens are automatically refreshed when expired
• Refresh tokens are stored securely and reused
• If refresh fails, re-run the authentication flow

Updating Credentials

To update credentials:

1. Replace credentials.json with new OAuth 2.0 credentials
2. Delete token.json to force re-authentication
3. Restart the server to trigger new OAuth flow

Development

# Development mode with auto-reload
npm run dev

# Build TypeScript
npm run build

# Run linting
npm run lint

# Format code
npm run format

Troubleshooting

Authentication Issues:

• Ensure Gmail API is enabled in Google Cloud Console
• Check that credentials.json contains valid OAuth 2.0 credentials
• Delete token.json and restart to re-authenticate

Connection Issues:

• Verify server is running on the correct port (default: 3000)
• Check firewall settings if accessing remotely
• Ensure MCP client configuration matches server URL

Permission Issues:

• Grant necessary Gmail permissions during OAuth flow
• Check Google Cloud Console for API quotas and limits

License

MIT License