Auralis Google

MCP server for Google Workspace integration with Claude AI

![npm version](https://www.npmjs.com/package/auralis-google) !Tools !Google APIs !License

![Deploy on Railway](https://railway.com/template/auralis-google?referralCode=auralis)

Auralis Google provides seamless integration between Claude AI and Google Workspace services through the Model Context Protocol (MCP). Access Gmail, Calendar, Drive, Docs, and Sheets directly from Claude.

Features

Gmail: Search messages, read emails, send emails, manage labels
Calendar: List events, create/update/delete events, list calendars
Drive: List files, search, read content, create/delete files and folders
Docs: Read documents, append text, create new docs
Sheets: Full spreadsheet management - read, write, append, delete rows, manage sheets

Installation

Option 1: npm (Recommended)

npm install -g auralis-google

Option 2: Docker

docker pull antonpme/auralis-google
docker run -p 3000:3000 \
  -e GOOGLE_CLIENT_ID=your_client_id \
  -e GOOGLE_CLIENT_SECRET=your_client_secret \
  -e GOOGLE_REDIRECT_URI=http://localhost:3000/oauth/callback \
  antonpme/auralis-google

Option 3: Clone and Build

git clone https://github.com/antonpme/auralis-google.git
cd auralis-google
npm install
npm run build

Google Cloud Setup

Before using Auralis Google, you need to create OAuth credentials:

Go to Google Cloud Console
Create a new project or select existing one
Enable the following APIs:

Gmail API
Google Calendar API
Google Drive API
Google Docs API
Google Sheets API

Go to Credentials → Create Credentials → OAuth client ID
Select Web application
Add authorized redirect URI: http://localhost:3000/oauth/callback
Copy Client ID and Client Secret

Configuration

Claude Desktop (stdio mode)

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "google": {
      "command": "auralis-google",
      "env": {
        "MCP_MODE": "stdio",
        "GOOGLE_CLIENT_ID": "your_client_id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_REDIRECT_URI": "http://localhost:3000/oauth/callback"
      }
    }
  }
}

HTTP Mode (Railway/Docker)

Set these environment variables:

| Variable | Description | |----------|-------------| | PORT | Server port (default: 3000) | | MCP_MODE | Set to http for HTTP mode (default) | | GOOGLE_CLIENT_ID | OAuth Client ID | | GOOGLE_CLIENT_SECRET | OAuth Client Secret | | GOOGLE_REDIRECT_URI | OAuth callback URL | | TOKENS_PATH | Path to store tokens (default: ./data/tokens.json) |

HTTP Endpoints:

| Endpoint | Method | Description | |----------|--------|-------------| | /mcp | POST | MCP protocol endpoint (Streamable HTTP) | | /auth?account=xxx | GET | Start OAuth flow for account | | /oauth/callback | GET | OAuth callback handler | | /health | GET | Health check |

Authentication

On first use, you need to authenticate with Google:

HTTP Mode:

Open http://localhost:3000/auth?account=personal in browser
Sign in with your Google account
Grant permissions
You'll see "✅ Authenticated as your@email.com"

Stdio Mode: You'll need to run the server in HTTP mode first to complete OAuth, then switch to stdio.

Multiple Accounts

You can authenticate multiple Google accounts:

/auth?account=personal
/auth?account=work
/auth?account=client

Then specify the account when using tools:

{
  "account": "work",
  "query": "is:unread"
}

Tools Reference

Account Management

| Tool | Description | |------|-------------| | google_list_accounts | List all authenticated Google accounts |

Gmail (4 tools)

| Tool | Description | |------|-------------| | google_gmail_search | Search Gmail messages with query | | google_gmail_read | Read a specific email by ID | | google_gmail_send | Send an email | | google_gmail_labels | List Gmail labels |

Calendar (5 tools)

| Tool | Description | |------|-------------| | google_calendar_list | List all calendars | | google_calendar_list_events | List events with optional time filter | | google_calendar_create_event | Create a new event | | google_calendar_update_event | Update an existing event | | google_calendar_delete_event | Delete an event |

Drive (8 tools)

| Tool | Description | |------|-------------| | google_drive_list | List files in Drive or folder | | google_drive_search | Search files by content | | google_drive_get | Get file metadata | | google_drive_read | Read file content (text/Google Docs) | | google_drive_create | Create a new file | | google_drive_delete | Delete a file | | google_drive_create_folder | Create a folder | | google_drive_move | Move file to another folder |

Docs (3 tools)

| Tool | Description | |------|-------------| | google_docs_read | Read a Google Doc | | google_docs_append | Append text to a Doc | | google_docs_create | Create a new Google Doc |

Sheets (10 tools)

| Tool | Description | |------|-------------| | google_sheets_create | Create a new spreadsheet | | google_sheets_read | Read data from range | | google_sheets_append | Append rows to sheet | | google_sheets_update | Update cells in range | | google_sheets_info | Get spreadsheet metadata | | google_sheets_delete_rows | Delete rows | | google_sheets_clear | Clear cells in range | | google_sheets_add_sheet | Add new sheet tab | | google_sheets_delete_sheet | Delete sheet tab | | google_sheets_rename_sheet | Rename sheet tab |

Usage Examples

Search unread emails

Search my Gmail for unread messages from last week

Create calendar event

Create a meeting called "Project Review" tomorrow at 3pm for 1 hour

Read spreadsheet data

Read all data from my Budget spreadsheet

Send email

Send an email to john@example.com with subject "Meeting Notes" and the summary of our discussion

Comparison with Google Workspace CLI

Google released the Google Workspace CLI (gws) in March 2026 — a Rust-based CLI + MCP server that dynamically discovers all Google APIs. It's an impressive project. Here's how it compares:

At a Glance

| | Auralis Google | Google Workspace CLI | |---|---|---| | Focus | Production MCP server | CLI tool + MCP server | | Maturity | Stable, production-tested | Pre-v1.0, rapid iteration | | Language | TypeScript (hackable) | Rust (binary, not modifiable) | | Transport | HTTP Streamable + Stdio | Stdio only | | Remote deployment | ✅ Railway, Docker, any cloud | ❌ Local only | | Google services | 5 (Gmail, Calendar, Drive, Docs, Sheets) | 26+ (auto-discovered) | | MCP tools | 31 (focused) | 200-400 full / ~26 compact | | Multi-account | ✅ Stable | ⚠️ Documented, auth issues | | Custom OAuth app | ✅ Your own GCP project | ✅ Your own GCP project | | Scope control | 5 scopes, always within limits | 85+ recommended, hits unverified app caps | | Official Google product | No | No ("not officially supported") |

Why Auralis Google

1. Remote-first architecture

Auralis Google runs on Railway, Docker, or any cloud provider. Your AI assistant accesses Google APIs from anywhere — not just your local machine. gws MCP mode only works over stdio (local process).

2. Production-stable

Real-world usage across multiple accounts. No auth loops, no token refresh issues, no scope conflicts. gws is under active development with open auth-related issues.

3. Right-sized tool surface

31 purpose-built tools that cover the core Google Workspace workflow. Your AI doesn't burn context tokens loading 200+ tool definitions. Each tool has clear input schemas with Zod validation.

4. Hackable

TypeScript source you can read, modify, and extend. Need a custom tool? Add it in 20 lines. Rust binaries don't offer that flexibility.

When to consider gws instead

You need Google services beyond the core 5 (Slides, Forms, Tasks, Meet, Chat, Keep, Admin)
You want CLI access to Google APIs (not just MCP)
You prefer a single tool for everything and don't need remote deployment
You're comfortable with pre-v1.0 software and can work through auth issues

Summary

| Scenario | Recommendation | |----------|---------------| | Production MCP server for AI assistants | Auralis Google | | Local CLI for quick Google API calls | gws | | Need Slides, Forms, Tasks, or Meet | gws (or add to Auralis Google) | | Multi-machine / cloud deployment | Auralis Google | | Want to modify or extend the code | Auralis Google |

Our take: Use Auralis Google for production AI workflows. Keep an eye on gws as it matures — it could become a great complement for services outside the core 5.

Railway Deployment

Fork this repository
Connect to Railway
Set environment variables in Railway dashboard
Deploy

Or use the railway.json included in this repo.

Architecture

auralis-google/
├── src/
│   ├── index.ts      # MCP server + Express endpoints
│   ├── auth.ts       # OAuth2 management
│   └── tools/
│       ├── gmail.ts
│       ├── calendar.ts
│       ├── drive.ts
│       ├── docs.ts
│       └── sheets.ts
├── dist/             # Compiled JavaScript
├── data/             # Token storage (gitignored)
├── Dockerfile
├── railway.json
└── package.json

Security

OAuth tokens are stored locally in ./data/tokens.json
Tokens are automatically refreshed when expired
Never commit your data/ folder or .env files
Use environment variables for credentials

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

MIT License - see LICENSE file.

auralis-google