Google Services MCP Server

A Model Context Protocol (MCP) server that exposes Google services — specifically Gmail and Google Docs — as standardized tools for AI agents.

This allows MCP-compatible agents (like Claude Desktop, Cursor, or custom agents) to seamlessly send/draft emails and append content to Google Docs on your behalf.

Capabilities (Tools)

Related MCP server: MCP Google Workspace Server

Prerequisites

1. Node.js: Version 20 or higher.

2. Google Cloud Project: You need to set up a project and obtain OAuth 2.0 credentials.

🛠️ Google Cloud Setup Guide

1. Go to the Google Cloud Console.

2. Create a new project (e.g., "MCP Server").

3. Go to APIs & Services > Library.

   • Search for and enable the Gmail API.

   • Search for and enable the Google Docs API.

4. Go to APIs & Services > OAuth consent screen.

   • Choose External (or Internal if you have a Workspace).

   • Fill out the App Name, User support email, and Developer contact information.

   • Click Save and Continue.

   • Under Scopes, add:

     • https://www.googleapis.com/auth/gmail.send

     • https://www.googleapis.com/auth/gmail.compose

     • https://www.googleapis.com/auth/documents

   • Finish the consent screen setup.

5. Go to APIs & Services > Credentials.

   • Click Create Credentials > OAuth client ID.

   • Application type: Web application.

   • Name: "MCP Server Local".

   • Under Authorized redirect URIs, add exactly: http://localhost:3000/oauth2callback

   • Click Create.

   • Note down your Client ID and Client Secret.

🚀 Installation & Authentication

1. Clone or copy this repository.

2. Install dependencies:

   npm install

3. Copy the environment template:

   cp .env.example .env

4. Open .env and fill in your GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET.

5. Run the authentication script to obtain your refresh token:

   npm run authenticate

6. Follow the prompt in your browser to authorize the app. Once completed, the terminal will output a GOOGLE_REFRESH_TOKEN.

7. Add the GOOGLE_REFRESH_TOKEN to your .env file.

8. Build the server:

   npm run build

🔌 Connecting to an MCP Client

Claude Desktop

Add the following to your claude_desktop_config.json (usually found at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "google-services": {
      "command": "node",
      "args": [
        "/absolute/path/to/google-mcp-server/build/index.js"
      ],
      "env": {
        "GOOGLE_CLIENT_ID": "your_client_id",
        "GOOGLE_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_REFRESH_TOKEN": "your_refresh_token",
        "GOOGLE_REDIRECT_URL": "http://localhost:3000/oauth2callback"
      }
    }
  }
}

Note: Replace /absolute/path/to/ with the actual path to this folder.

🔧 Architecture

This server is built using the MCP SDK v2. It uses the stdio transport to communicate with the host agent. The architecture is designed to be highly modular. Adding a new Google service requires:

1. Creating a new folder in src/tools/.

2. Defining Zod schemas for inputs.

3. Implementing the Google API logic.

4. Calling the registration function in src/tools/index.ts.

It includes built-in exponential backoff for rate limiting and structured error handling for a robust agent experience.

⚠️ Troubleshooting

• Authentication Error / Missing Token: Make sure you ran npm run authenticate and copied the refresh token into your .env file or Claude config.

• Permission Denied (403): Ensure you added all 3 required scopes during the Google Cloud OAuth consent screen setup, and that the account you authenticated with has access to the target Google Doc.

• Resource Not Found (404): Double check the document_id. It should be the string between /d/ and /edit in the Google Docs URL.