Google Workspace MCP Server

A generic, agent-agnostic Model Context Protocol (MCP) server that exposes Gmail and Google Docs capabilities as tools. Any MCP-compatible client (Antigravity, Claude Desktop, custom agents) can connect and use these tools without code changes.

Available Tools

Tool	Description
gmail_send_email	Send an email via Gmail on behalf of the authenticated user
gmail_create_draft	Create a draft email in Gmail without sending
gdocs_append_content	Append text content to the end of a Google Doc

Prerequisites

• Node.js 18 or later
• A Google Cloud project with billing enabled (or free tier)

Google Cloud Setup

1. Create a Google Cloud Project

1. Go to Google Cloud Console.
2. Create a new project (or select an existing one).

2. Enable APIs

Enable the following APIs for your project:

• Gmail API: Enable here
• Google Docs API: Enable here

3. Create OAuth 2.0 Credentials

1. Go to APIs & Services → Credentials.
2. Click Create Credentials → OAuth client ID.
3. Select Desktop app as the application type.
4. Name it (e.g., "MCP Server") and click Create.
5. Download or copy the Client ID and Client Secret.

4. Configure the OAuth Consent Screen

1. Go to APIs & Services → OAuth consent screen.
2. Select External user type (or Internal if using Workspace).
3. Fill in the required app info and add the following scopes:
   • https://www.googleapis.com/auth/gmail.send
   • https://www.googleapis.com/auth/gmail.compose
   • https://www.googleapis.com/auth/documents
4. Add your Google account as a test user (required for external apps in testing).

Installation

# Clone or navigate to the project directory
cd mcp-server

# Install dependencies
npm install

# Copy the environment template
cp .env.example .env

Edit .env and fill in your Google credentials:

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REDIRECT_URI=urn:ietf:wg:oauth:2.0:oob
GOOGLE_TOKEN_PATH=./token.json

Authorization

Run the one-time authorization flow to grant the server access to your Google account:

npm run authorize

This will:

1. Display a URL — open it in your browser.
2. Sign in with your Google account and grant access.
3. Paste the authorization code back into the terminal.
4. Save the OAuth tokens to token.json.

Note: You only need to do this once. Tokens refresh automatically after that.

Running the Server

Development (with hot reload)

npm run dev

Production

npm run build
npm start

Connecting to MCP Clients

Antigravity

Add to your Antigravity MCP settings:

{
  "mcpServers": {
    "google-workspace": {
      "command": "node",
      "args": ["C:/path/to/mcp-server/dist/index.js"]
    }
  }
}

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "google-workspace": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"]
    }
  }
}

MCP Inspector (Testing)

Use the MCP Inspector to test your tools interactively:

npx @modelcontextprotocol/inspector node dist/index.js

Tool Schemas

gmail_send_email

{
  "to": "recipient@example.com",
  "subject": "Hello from MCP",
  "body": "This email was sent by an AI agent via the MCP server.",
  "cc": "cc@example.com",
  "bcc": ["bcc1@example.com", "bcc2@example.com"],
  "body_html": "<h1>Hello</h1><p>HTML email body</p>"
}

gmail_create_draft

Same schema as gmail_send_email. Creates a draft without sending.

gdocs_append_content

{
  "document_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVf2oVzk",
  "content": "This text was appended by an AI agent.",
  "add_newline": true
}

Troubleshooting

Problem	Solution
Missing GOOGLE_CLIENT_ID	Copy .env.example to .env and fill in your credentials
No OAuth tokens found	Run npm run authorize to complete the consent flow
Token refresh failed	Delete token.json and run npm run authorize again
403 Forbidden	Ensure the Gmail and Docs APIs are enabled in your Google Cloud project
Invalid document ID	The document ID is the long string in the URL: docs.google.com/document/d/{ID}/edit
Access denied	Make sure your account is added as a test user in the OAuth consent screen
401 Unauthorized (cloud)	Set Authorization: Bearer <API_KEY> header when connecting to the remote server
GOOGLE_TOKENS_JSON decode error	Re-run npm run export-token locally and update the env var

Deploy to Railway

Prerequisites

• The MCP server running locally with a valid token.json (complete the Authorization steps first)
• A Railway account
• A GitHub repository with this code pushed

Step 1: Export Your Token

npm run export-token

This outputs a Base64-encoded string of your token.json. Copy it — you'll need it in Step 3.

Step 2: Create Railway Service

1. Go to Railway Dashboard.
2. Click New Project → Deploy from GitHub Repo.
3. Select your repository.
4. Railway will auto-detect the Dockerfile and begin building.

Step 3: Set Environment Variables

In the Railway service dashboard, go to Variables and add:

Variable	Value
TRANSPORT	http
GOOGLE_CLIENT_ID	Your Google OAuth client ID
GOOGLE_CLIENT_SECRET	Your Google OAuth client secret
GOOGLE_TOKENS_JSON	The Base64 string from Step 1
API_KEY	A secret key of your choice (for securing the endpoint)

Note: PORT is injected automatically by Railway. Do not set it manually.

Step 4: Deploy

Railway will automatically build and deploy. Once live, you'll get a public URL like:

https://your-app-name.up.railway.app

Step 5: Verify

# Health check
curl https://your-app-name.up.railway.app/health

# Test MCP endpoint (replace YOUR_API_KEY)
curl -X POST https://your-app-name.up.railway.app/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"capabilities":{}},"id":1}'

Step 6: Connect Remote MCP Client

Configure your MCP client to connect to the deployed server. Example for clients that support Streamable HTTP:

{
  "mcpServers": {
    "google-workspace-remote": {
      "url": "https://your-app-name.up.railway.app/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Project Structure

├── src/
│   ├── index.ts                  # Server entry point (stdio + HTTP dual transport)
│   ├── auth/
│   │   └── google-auth.ts        # OAuth2 authentication (file + env var dual mode)
│   ├── services/
│   │   ├── gmail.service.ts      # Gmail API logic
│   │   └── gdocs.service.ts      # Google Docs API logic
│   ├── tools/
│   │   ├── gmail-send-email.ts   # gmail_send_email tool
│   │   ├── gmail-create-draft.ts # gmail_create_draft tool
│   │   └── gdocs-append.ts       # gdocs_append_content tool
│   └── utils/
│       └── mime.ts               # MIME message builder
├── scripts/
│   ├── authorize.ts              # OAuth consent flow script
│   └── export-token.ts           # Token export for cloud deployment
├── Dockerfile                    # Multi-stage Docker build
├── railway.toml                  # Railway deployment config
├── .env.example                  # Environment variable template
├── package.json
├── tsconfig.json
└── README.md

License

MIT