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)

Tool	Description
gmail_send_email	Send an email to one or more recipients with subject, body (text/html), and optional CC/BCC.
gmail_draft_email	Create a draft email in your Gmail account without sending it.
gdocs_append_content	Append text content to the end of an existing Google Doc, with optional formatting (heading level, bold, italic).

---

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.