Google Workspace MCP Service
A production-ready Google Workspace MCP service providing 84 specialized tools for comprehensive Google Workspace automation. Designed to run as a persistent background service integrating with Rube MCP for centralized OAuth authentication.
🚀 Features
- 84 Custom Tools: Complete Google Workspace API coverage (83 tools + 1 auth via Composio)
- MCP Service: Persistent background service with PM2 process management
- Centralized Auth: OAuth handled by Composio/Rube (no client secrets on desktops)
- TypeScript: Full type safety with modern ES2022 features
- ES Modules: Native ES module support throughout
- Auto-startup: Configurable boot-time service activation
- Health Monitoring: Built-in health endpoints for service monitoring
- PKCE Compliant: Solves security compliance for remote workforce
📋 Prerequisites
🛠️ Quick Start
1. Installation
# Clone or download the project
git clone <repository-url>
cd composio-google-workspace
# Install dependencies
npm install
2. Environment Setup
# Copy environment template
cp .env.example .env
# Edit .env with your API keys
COMPOSIO_API_KEY=your_composio_api_key_here
ANTHROPIC_API_KEY=your_anthropic_api_key_here
3. Development
# Run in development mode
npm run dev
# Or build and run
npm run build
npm start
🏗️ Project Structure
src/
├── agents/ # AI agent implementations
│ └── google-workspace-agent.ts
├── tools/ # Custom tool definitions
│ └── custom-tools.ts
├── composio-client.ts # Composio SDK initialization
└── index.ts # Main application entry
🤖 Google Workspace Agent
The GoogleWorkspaceAgent class provides high-level methods for common workspace tasks:
import { GoogleWorkspaceAgent } from './src/agents/google-workspace-agent.js'
const agent = new GoogleWorkspaceAgent('user-123')
await agent.initialize(['gmail', 'googlecalendar'])
// Send emails
await agent.sendEmail('colleague@company.com', 'Project Update', 'Here is the status...')
// Create calendar events
await agent.createCalendarEvent({
title: 'Team Standup',
start: '2024-01-15T09:00:00Z',
end: '2024-01-15T09:30:00Z',
attendees: ['team@company.com']
})
// Complex workflows
await agent.scheduleMeetingWithInvites({
title: 'Q1 Planning',
start: '2024-01-20T14:00:00Z',
end: '2024-01-20T15:00:00Z',
attendees: ['stakeholder1@company.com', 'stakeholder2@company.com'],
agenda: 'Q1 objectives and resource allocation'
})
Create specialized tools for your workspace needs:
import { initializeCustomTools } from './src/tools/custom-tools.js'
// Initialize all custom tools
const tools = await initializeCustomTools()
// Available custom tools:
// - EMAIL_ANALYTICS: Analyze email patterns
// - MEETING_OPTIMIZER: Find optimal meeting times
// - DOCUMENT_INTELLIGENCE: Extract insights from documents
// - WORKSPACE_WORKFLOW: Automate cross-app workflows
🔐 Authentication Flow
Option 1: Interactive Setup
import { setupAuthentication, waitForAuthentication } from './src/composio-client.js'
// Setup Gmail authentication
const connectionRequest = await setupAuthentication('user-123', 'gmail')
console.log('Visit this URL:', connectionRequest.redirectUrl)
// Wait for user to complete OAuth flow
const connectedAccount = await waitForAuthentication(connectionRequest.id)
console.log('Gmail connected:', connectedAccount.id)
Configure connections via the Composio Dashboard and reference them by ID.
📚 Available Scripts
# Development
npm run dev # Start development server
npm run build # Build for production
npm run preview # Preview production build
npm start # Run built application
# Code Quality
npm run typecheck # TypeScript type checking
npm run lint # ESLint code linting
npm run lint:fix # Fix ESLint issues automatically
npm run format # Format code with Prettier
npm run format:check # Check code formatting
🔗 Integration Examples
Gmail Integration
// Fetch recent emails
const emails = await agent.getRecentEmails(10, 'is:unread')
// Send email with attachments
await agent.sendEmail('client@company.com', 'Proposal', 'Please find attached...', {
attachments: ['path/to/proposal.pdf']
})
Calendar Integration
// Get upcoming events
const events = await agent.getUpcomingEvents(5)
// Create recurring meeting
await agent.createCalendarEvent({
title: 'Weekly Sync',
start: '2024-01-15T10:00:00Z',
end: '2024-01-15T10:30:00Z',
recurrence: ['RRULE:FREQ=WEEKLY;BYDAY=MO']
})
Google Drive Integration
// Upload documents
await agent.uploadToDrive('report.md', reportContent)
// Search files
const files = await agent.searchDriveFiles('type:document modified:2024')
🚀 Advanced Workflows
Daily Summary Generation
// Generate comprehensive daily summary
const summary = await agent.generateDailySummary('2024-01-15')
console.log(summary)
// Includes email activity, calendar events, and insights
Meeting Orchestration
// Complete meeting workflow: schedule + invites + follow-up
await agent.scheduleMeetingWithInvites({
title: 'Product Review',
start: '2024-01-20T15:00:00Z',
end: '2024-01-20T16:00:00Z',
attendees: ['product@company.com', 'engineering@company.com'],
agenda: 'Q1 product roadmap review and prioritization',
location: 'Conference Room A'
})
🛡️ Error Handling
The project includes comprehensive error handling:
try {
await agent.sendEmail('invalid-email', 'Test', 'Body')
} catch (error) {
console.error('Email failed:', error.message)
// Handle specific error cases
}
📖 API Reference
Composio Client
initializeComposio() - Initialize SDK connectiongetAvailableTools(toolkits, userId) - List available toolssetupAuthentication(userId, toolkit) - Start OAuth flowwaitForAuthentication(requestId) - Wait for auth completionexecuteTool(toolSlug, userId, arguments) - Execute any tool
Google Workspace Agent
initialize(services) - Setup agent with required servicessendEmail() - Send emails with attachmentsgetRecentEmails() - Fetch and filter emailscreateCalendarEvent() - Create calendar eventsgetUpcomingEvents() - List upcoming eventsuploadToDrive() - Upload files to DrivesearchDriveFiles() - Search Drive contentgenerateDailySummary() - Generate daily activity summary
🔧 Configuration
TypeScript Configuration
The project uses modern TypeScript settings in tsconfig.json:
- Target: ES2022
- Module: ESNext
- Strict mode enabled
- Path aliases supported (
@/ → src/)
Vite Configuration
Optimized for Node.js development:
- ES modules output
- Source maps enabled
- Proper external handling
- Path alias resolution
Code Quality
- ESLint: TypeScript-aware linting with recommended rules
- Prettier: Consistent code formatting
- Pre-commit hooks: Automated formatting and linting
🤝 Contributing
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes and add tests
- Run quality checks:
npm run lint && npm run typecheck - Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
📄 License
This project is licensed under the ISC License. See the LICENSE file for details.
🆘 Troubleshooting
Common Issues
Authentication Errors
# Verify API keys are set
npm run dev
# Check console for authentication status
TypeScript Errors
# Run type checking
npm run typecheck
# Check for missing dependencies
npm install
Build Issues
# Clear cache and rebuild
rm -rf dist node_modules
npm install
npm run build
Getting Help
🔮 What's Next?
- Add Anthropic Claude integration for AI-powered email responses
- Implement workflow scheduling and automation
- Add support for Google Sheets data processing
- Create dashboard for monitoring agent activities
- Add unit tests and CI/CD pipeline
Built with ❤️ using Composio.dev - The platform for AI agents to take actions in the real world.