Google Workspace MCP Server (Gmail + Google Docs)

A Model Context Protocol (MCP) server that exposes Google Workspace capabilities — specifically Gmail and Google Docs — as standardized MCP tools.

Features

• send_email: Send an email immediately via the authenticated Gmail account.
• draft_email: Create a draft in the authenticated Gmail account without sending.
• append_to_google_doc: Append text content to the end of an existing Google Doc.

Setup Instructions

1. Google Cloud Project Setup

1. Go to the Google Cloud Console.
2. Create a new project or select an existing one.
3. Navigate to APIs & Services > Library.
4. Search for and enable the Gmail API and Google Docs API.
5. Navigate to APIs & Services > OAuth consent screen.
   • Configure the consent screen (External or Internal).
   • Add the following scopes:
     • https://www.googleapis.com/auth/gmail.send
     • https://www.googleapis.com/auth/gmail.compose
     • https://www.googleapis.com/auth/documents
   • Add your email address as a Test User if your app is in testing mode.
6. Navigate to APIs & Services > Credentials.
   • Click Create Credentials > OAuth client ID.
   • Choose Desktop app as the application type.
   • Click Create.
   • Download the JSON file and rename it to credentials.json. Place it in the root of this project.

2. Environment Setup

1. Copy .env.example to .env (optional, as defaults are used if not provided).
2. Install the project dependencies:

   pip install -e .
   

3. First Run (Authentication)

Before an MCP client can use the server, you must authenticate it manually to generate the token.json file.

Run the server directly:

gmail-docs-mcp

This will open a browser window asking you to log in with your Google account and grant the requested permissions. Once completed, a token.json file will be created. You can then stop the server (Ctrl+C).

4. MCP Client Configuration

Configure your MCP client (e.g., Claude Desktop) to run this server. Add the following to your MCP client's configuration file:

{
  "mcpServers": {
    "google-workspace": {
      "command": "gmail-docs-mcp",
      "env": {
        "GOOGLE_CREDENTIALS_PATH": "/absolute/path/to/credentials.json",
        "GOOGLE_TOKEN_PATH": "/absolute/path/to/token.json"
      }
    }
  }
}

Note: Make sure to use absolute paths for the credentials and token files.

Testing

Run unit tests with pytest:

pip install -e ".[dev]"
pytest

Manual Smoke-Test Checklist

1. Send test email: Invoke send_email with your own email address to verify receipt.
2. Create draft: Invoke draft_email and check your Gmail Drafts folder.
3. Append to a doc: Create a test Google Doc, copy its URL or ID, and invoke append_to_google_doc. Check the document to verify the text was appended at the end.