Google Services MCP

April 14, 2025 · View on GitHub

A Model Context Protocol server that provides access to Google Gmail and Calendar services for use with Claude and other MCP-compatible AI assistants.

Features

Gmail Integration
- List and search emails with smart date filtering
- Read email content with optional attachment handling
- Compose and send emails
- Manage labels
Calendar Integration
- List and search calendar events
- Create new calendar events
- Support for both all-day and timed events
- Time period shortcuts (today, tomorrow, this week, etc.)

Performance Optimization

Attachment processing is optional and disabled by default to reduce API usage
Uses metadata format instead of full format when attachments aren't needed
Offers fine-grained control over result limits to manage API quota usage

Setup Guide

Prerequisites

Node.js 18+ and npm
A Google Cloud project with Gmail and Calendar APIs enabled
OAuth 2.0 client credentials for a desktop application

Step 1: Google Cloud Setup

Create a Google Cloud Project:
- Go to the Google Cloud Console
- Click the project dropdown at the top and select "New Project"
- Enter a name for your project and click "Create"
- Wait for the project to be created and select it in the dropdown
Enable the Required APIs:
- In the sidebar, navigate to "APIs & Services" > "Library"
- Search for and enable the following APIs:
  - Gmail API
  - Google Calendar API
- For each API, click "Enable" and wait for the API to be enabled
Configure OAuth Consent Screen:
- Go to "APIs & Services" > "OAuth consent screen"
- Select "External" user type (unless you have a Google Workspace account)
- Click "Create"
- Fill in the required information:
  - App name
  - User support email
  - Developer contact information
- Click "Save and Continue"
- Add the following scopes:
  - https://www.googleapis.com/auth/gmail.readonly
  - https://www.googleapis.com/auth/gmail.send
  - https://www.googleapis.com/auth/gmail.compose
  - https://www.googleapis.com/auth/calendar
- Click "Save and Continue" and complete the remaining steps
Create OAuth Credentials:
- Go to "APIs & Services" > "Credentials"
- Click "Create Credentials" > "OAuth client ID"
- Select "Desktop app" as the Application type
- Enter a name for your OAuth client
- Click "Create"
- A popup will appear with your client ID and client secret
- Click "Download JSON" to download your credentials file

Step 2: MCP Server Setup

Clone the Repository:

git clone https://github.com/yourusername/mcp-google-services.git
cd mcp-google-services

Install Dependencies:
```
npm install
```
Prepare Credentials:
- Rename the downloaded OAuth credentials JSON file to client_secret.json
- Place this file in the root directory of the project
- Note your Client ID and Client Secret for later
Build the Server:
```
npm run build
```
Run the Authentication Setup:
```
npm run setup
```
This script will:
- Read the client_secret.json file
- Start a local web server on port 4100
- Open a browser window to the Google authorization page
- After you authorize, Google will redirect to your local server
- A token.json file will be created in the project root
Important: When authorizing, you'll see a "Google hasn't verified this app" warning. This is normal for apps you create yourself. Click "Continue" to proceed.

Step 3: MCP Configuration

Add this server to your MCP configuration file. The location depends on your setup:

For Claude VSCode Extension: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json (macOS)
For Claude Desktop App: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

Add the following to your config file:

{
  "mcpServers": {
    "google-services": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/mcp-google-services/build/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "YOUR_CLIENT_ID_HERE",
        "GOOGLE_CLIENT_SECRET": "YOUR_CLIENT_SECRET_HERE",
        "GOOGLE_REDIRECT_URI": "http://localhost:4100/code"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Replace:

/ABSOLUTE/PATH/TO/mcp-google-services with the absolute path to the repository on your system
YOUR_CLIENT_ID_HERE with your actual client ID from the OAuth credentials
YOUR_CLIENT_SECRET_HERE with your actual client secret from the OAuth credentials

Troubleshooting

Authorization Error: If you see "Error: redirect_uri_mismatch", make sure the redirect URI in your Google Cloud Console OAuth credential settings matches exactly with "http://localhost:4100/code".
Server Not Found: If you get "MCP server not connected", check:
- The path in your MCP configuration is correct
- You've run npm run build and have a build directory
- Your environment variables are set correctly
Token Expired: If you see authentication errors after a long period:
- Delete the token.json file
- Run npm run setup again to re-authenticate

Usage

Gmail Examples

Listing recent emails

<use_mcp_tool>
<server_name>google-services</server_name>
<tool_name>gmail_list_messages</tool_name>
<arguments>
{
  "maxResults": 5
}
</arguments>
</use_mcp_tool>

Searching emails

<use_mcp_tool>
<server_name>google-services</server_name>
<tool_name>gmail_search</tool_name>
<arguments>
{
  "query": "from:example@gmail.com subject:important",
  "maxResults": 3,
  "includeAttachments": false
}
</arguments>
</use_mcp_tool>

Getting email by ID

<use_mcp_tool>
<server_name>google-services</server_name>
<tool_name>gmail_get_message</tool_name>
<arguments>
{
  "messageId": "MESSAGE_ID_HERE",
  "includeAttachments": true
}
</arguments>
</use_mcp_tool>

Calendar Examples

Listing today's events

<use_mcp_tool>
<server_name>google-services</server_name>
<tool_name>calendar_search_events</tool_name>
<arguments>
{
  "query": "",
  "timePeriod": "today"
}
</arguments>
</use_mcp_tool>

Creating a new event

<use_mcp_tool>
<server_name>google-services</server_name>
<tool_name>calendar_create_event</tool_name>
<arguments>
{
  "summary": "Team Meeting",
  "description": "Weekly team sync",
  "startDateTime": "2025-04-20T15:00:00Z",
  "endDateTime": "2025-04-20T16:00:00Z",
  "timeZone": "America/Los_Angeles"
}
</arguments>
</use_mcp_tool>

Security Notes

Sensitive files like token.json and client_secret.json are excluded in .gitignore
No credentials are hardcoded in the source code
The MCP server uses environment variables for authentication
Make sure you don't accidentally commit your credentials
Consider adding IP restrictions to your OAuth client in Google Cloud Console for extra security

License

MIT

Contributing

Contributions are welcome! Feel free to submit pull requests or open issues for bugs and feature requests.