Generic MCP Server for Google Workspace

A Model Context Protocol (MCP) server that securely exposes Google Workspace capabilities to AI Agents (like Claude Desktop, OpenAI, or Cursor) through standardized MCP tools.

This server acts as a bridge, allowing any MCP-compatible AI client to interact with Google APIs without requiring custom integrations inside the agent itself.

Features & Tools

Currently, the server exposes the following tools:

• gmail_send_email: Sends an email (supports To, Cc, Bcc, Subject, and Text/HTML bodies).
• gmail_create_draft: Creates an email draft in the authenticated user's account.
• gdocs_append_content: Appends text to the end of a specific Google Document (requires the Document ID).

---

Prerequisites

1. Node.js (v18 or newer)
2. Google Cloud Console Project:
   • Enable the Gmail API and Google Docs API.
   • Create an OAuth 2.0 Client ID (Web application).
   • Set the Authorized Redirect URI to http://localhost (or your domain).

---

Setup & Local Authentication

1. Install Dependencies

   npm install
   

2. Configure Environment Variables Copy .env.example to .env and add your Google credentials:

   GOOGLE_CLIENT_ID=your_client_id_here
   GOOGLE_CLIENT_SECRET=your_client_secret_here
   GOOGLE_REDIRECT_URI=http://localhost
   

3. Generate OAuth Tokens To grant the server access to your Google account, you must complete the OAuth flow once. Run the token generation script:

   npm run build
   node dist/auth/generate_token.js
   

   Follow the on-screen instructions. The script will save your access and refresh tokens locally in .tokens.json.

---

Running the Server

Local Development

To run the server locally, you can use the standard build and start scripts:

npm run build
npm start

Note: The server is configured to run over HTTP using Server-Sent Events (SSE) by default on http://localhost:3000/sse.

Cloud Deployment (Railway)

This server is pre-configured to be easily deployable to cloud services like Railway.

When deploying to a remote host:

1. Ensure the TOKEN_PATH environment variable is set to a persistent volume (e.g., /app/data/.tokens.json), as the local file system in most cloud providers is ephemeral.
2. The server will automatically bind to the PORT environment variable provided by your cloud host.

For full instructions, see the Deployment Plan.

---

Connecting an AI Agent

To connect an AI Agent to this MCP Server, add the HTTP URL to your agent's MCP configuration file (e.g., in Claude Desktop).

{
  "mcpServers": {
    "google-workspace": {
      "url": "http://localhost:3000/sse"
    }
  }
}

(If deployed remotely, replace the URL with your remote domain, e.g., https://my-server.up.railway.app/sse).