Auralis Google

MCP server for Google Workspace integration with Claude AI

npm version

Deploy on Railway

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:

1. Go to Google Cloud Console
2. Create a new project or select existing one
3. Enable the following APIs:
   • Gmail API
   • Google Calendar API
   • Google Drive API
   • Google Docs API
   • Google Sheets API
4. Go to Credentials → Create Credentials → OAuth client ID
5. Select Web application
6. Add authorized redirect URI: http://localhost:3000/oauth/callback
7. 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:

1. Open http://localhost:3000/auth?account=personal in browser
2. Sign in with your Google account
3. Grant permissions
4. You'll see "✅ Authenticated as [email protected]"

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 [email protected] 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

1. Fork this repository
2. Connect to Railway
3. Set environment variables in Railway dashboard
4. 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.

Links

• GitHub Repository
• NPM Package
• Auralis Commander - Windows MCP server