ripolissimogit/google-workspace-mcp-server

Google Workspace MCP Server v2.0.0

Enterprise-grade Model Context Protocol (MCP) server for seamless Google Workspace integration with advanced features including connection pooling, intelligent retry logic, comprehensive logging, and multi-transport support.

Features

🚀 Core Capabilities

• Document Management: Create, search, and manage Google Docs with advanced content handling
• Email Operations: Read and search Gmail messages with intelligent filtering
• Calendar Integration: List and analyze calendar events with comprehensive statistics
• Drive Operations: Advanced file search with content analysis and metadata extraction
• Health Monitoring: Built-in health checks and performance metrics

🏗️ Enterprise Architecture

• Multi-Transport Support: Both STDIO and HTTP/SSE transports
• Connection Pooling: Optimized HTTP agent with keep-alive
• Intelligent Retry Logic: Exponential backoff with circuit breaker pattern
• Comprehensive Logging: Structured logging with Winston
• Configuration Management: Zod-based validation and environment handling
• Caching System: JWT client caching with automatic refresh

🔒 Security & Performance

• Domain-Wide Delegation: Service account impersonation for admin operations
• Input Validation: Comprehensive schema validation for all operations
• Error Handling: Graceful error handling with detailed logging
• Resource Management: Automatic cleanup and connection management
• Production Ready: Docker support with security hardening

Quick Start

Prerequisites

• Node.js 18+
• Google Workspace domain with admin access
• Service account with Domain-wide Delegation configured

Installation

1. Clone and install dependencies:

git clone https://github.com/ripolissimogit/google-workspace-mcp-server
cd google-workspace-mcp-server
npm install

2. Configure environment:

cp .env.example .env
# Edit .env with your Google Service Account credentials

3. Run the server:

# Development mode
npm run dev

# Production mode  
npm run build
npm start

# HTTP transport mode
MCP_TRANSPORT=http PORT=3000 npm start

Configuration

Environment Variables

Google Workspace Setup

1. Create Service Account:

   • Go to Google Cloud Console → IAM & Admin → Service Accounts
   • Create new service account with Drive, Docs, Gmail, Calendar APIs enabled
   • Download JSON key file

2. Enable Domain-Wide Delegation:

   • In Service Account settings, enable Domain-wide Delegation
   • Note the Client ID

3. Configure Admin Console:

   • Go to Google Admin Console → Security → API Controls
   • Add OAuth App with Client ID and required scopes:
     • https://www.googleapis.com/auth/drive
     • https://www.googleapis.com/auth/documents
     • https://www.googleapis.com/auth/gmail.readonly
     • https://www.googleapis.com/auth/calendar

Available Tools

📄 create_document

Create Google Documents with content and sharing options.

Parameters:

• title (required): Document title
• content (optional): Initial content
• parentFolderId (optional): Parent folder ID
• share (optional): Sharing configuration

Example:

{
  "title": "Project Report",
  "content": "This is the project report content...",
  "share": {
    "users": ["user@domain.com"],
    "permissions": "edit"
  }
}

🔍 search_files

Search Google Drive files with advanced filtering.

Parameters:

• query (required): Search query
• type (optional): File type filter
• limit (optional): Result limit (default: 20)
• includeContent (optional): Include file content (default: false)

📧 read_emails

Read Gmail messages with intelligent filtering.

Parameters:

• query (optional): Gmail search query
• maxResults (optional): Result limit (default: 10)
• labelIds (optional): Label filters (default: ["INBOX"])
• includeSpamTrash (optional): Include spam/trash (default: false)

📅 list_calendar_events

List calendar events with comprehensive analysis.

Parameters:

• calendarId (optional): Calendar ID (default: "primary")
• timeMin (optional): Start time (ISO 8601)
• timeMax (optional): End time (ISO 8601)
• maxResults (optional): Result limit (default: 50)

🏥 health_check

Comprehensive server health monitoring.

Parameters:

• includeApiTests (optional): Test API connectivity (default: true)
• detailed (optional): Include detailed diagnostics (default: false)

Deployment

Docker Deployment

# Build image
docker build -t google-workspace-mcp .

# Run container
docker run -e SERVICE_ACCOUNT_KEY="$(cat service-account.json)" \
           -e DOMAIN_ADMIN="admin@yourdomain.com" \
           google-workspace-mcp

Smithery Platform

# Deploy to Smithery
smithery deploy

# Configure with your credentials in the Smithery dashboard

Development

Project Structure

src/
├── auth/              # Google authentication & caching
├── config/            # Configuration management
├── server/            # MCP server implementation
├── tools/             # Google Workspace tools
│   ├── google-drive/  # Drive operations
│   ├── gmail/         # Gmail operations  
│   ├── calendar/      # Calendar operations
│   └── system/        # Health checks
└── utils/             # Logging & retry utilities

Scripts

npm run dev          # Development with auto-reload
npm run build        # Production build
npm run lint         # ESLint checks
npm run test         # Run tests
npm run type-check   # TypeScript validation

API Reference

Health Endpoints (HTTP Transport)

• GET /health - Server health status
• GET /metrics - Performance metrics
• GET /api/info - API information
• GET /sse - MCP SSE endpoint

Resources (MCP Protocol)

• server://status - Current server status
• server://metrics - Usage metrics
• server://config - Configuration info

Troubleshooting

Common Issues

Authentication Errors:

• Verify service account JSON key format
• Check Domain-wide Delegation is enabled
• Ensure admin email has proper permissions
• Verify OAuth scopes in Admin Console

API Rate Limits:

• Server implements exponential backoff automatically
• Adjust MAX_RETRIES and TIMEOUT as needed
• Monitor /metrics endpoint for rate limit info

Connection Issues:

• Check MAX_SOCKETS configuration
• Verify network connectivity to Google APIs
• Review server logs for detailed error info

Debug Mode

LOG_LEVEL=debug npm run dev

Contributing

1. Fork the repository
2. Create feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push branch: git push origin feature/amazing-feature
5. Open Pull Request

License

MIT License - see file for details.

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

Made with ❤️ using Claude Code