Gmail Google Docs Integration

A generic Model Context Protocol (MCP) server that exposes Google Workspace capabilities as MCP tools. The server enables AI agents to interact with Gmail and Google Docs.

Features

• Gmail: Send emails (To, CC, BCC, Subject, Body). Supports Plain Text and HTML.
• Google Docs: Append plain text to an existing Google Document.

Prerequisites

1. Node.js 18+ (if running locally)
2. Docker (if running via container)
3. Google Cloud Console Project
   • Enable Gmail API
   • Enable Google Docs API
   • Configure OAuth Consent Screen (add yourself as a Test User)
   • Create OAuth 2.0 Client IDs (Application Type: Web Application or Desktop)
   • Add http://localhost:3000/oauth2callback as an Authorized redirect URI (if Web Application).

Local Setup & Generating the Refresh Token

To run this server (either locally or on a platform like Railway), you need an OAuth Refresh Token.

1. Clone the repository and install dependencies:

   npm install
   

2. Copy the example environment file:

   cp .env.example .env
   

3. Open .env and add your GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET.
4. Run the token generation script:

   npm run generate-tokens
   

5. Follow the prompt, log in with your Google account, and grant permissions.
6. The script will automatically save your tokens into a tokens.json file in the root of the project. This file is loaded by the server when it runs.

Deployment

If you deploy this to a cloud environment (like Railway or Docker):

1. You must ensure the tokens.json file you generated locally is available to the container.
2. If you are uploading code directly, DO NOT commit tokens.json to a public repository. If it's a private repository, you can commit it.
3. If you want to change the file name, set the TOKEN_STORAGE_PATH environment variable.

Deployment (Railway)

This repository is optimized for deployment on Railway.

1. Push this repository to GitHub.
2. In Railway, create a new project from your GitHub repository.
3. In the Railway project settings, go to Variables and add:
   • GOOGLE_CLIENT_ID
   • GOOGLE_CLIENT_SECRET
   • TOKEN_STORAGE_PATH (if you want to override the default 'tokens.json')
   • GOOGLE_REDIRECT_URI (optional, defaults to http://localhost:3000/oauth2callback)
4. Railway will automatically detect the package.json, install dependencies, run the build script, and execute the start script using Nixpacks.
5. Alternatively, Railway can build from the provided Dockerfile if you configure it to use Docker.

Connecting an MCP Client

Once deployed or running locally, you can connect an MCP Client (like Claude Desktop) to it.

If running locally:

{
  "mcpServers": {
    "gmail-gdoc": {
      "command": "node",
      "args": ["/path/to/your/project/dist/index.js"]
    }
  }
}

If deployed, you will likely connect via an SSE or HTTP transport (if you modify the transport layer) or through a remote execution bridge, depending on your agent's capabilities. Note: The current implementation uses standard input/output (stdio), which is ideal for local agent execution. For remote cloud execution, consider switching the transport to SSE in src/server.ts.

Available Tools

send_email

• to: string[]
• cc?: string[]
• bcc?: string[]
• subject: string
• body: string
• isHtml?: boolean

append_to_google_doc

• documentId: string
• content: string