{"id":30586107,"url":"https://github.com/cfdude/composio-google-workspace","last_synced_at":"2025-08-29T11:43:25.426Z","repository":{"id":312193099,"uuid":"1046641694","full_name":"cfdude/composio-google-workspace","owner":"cfdude","description":"An MCP server for the Google Workspace developed for Composio.dev and Rube MCP","archived":false,"fork":false,"pushed_at":"2025-08-29T05:28:51.000Z","size":76,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-29T06:41:00.643Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cfdude.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-29T02:03:46.000Z","updated_at":"2025-08-29T05:28:55.000Z","dependencies_parsed_at":"2025-08-29T06:41:04.043Z","dependency_job_id":"4895946a-7cb9-4062-8f7e-6054719b1c1a","html_url":"https://github.com/cfdude/composio-google-workspace","commit_stats":null,"previous_names":["cfdude/composio-google-workspace"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/cfdude/composio-google-workspace","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfdude%2Fcomposio-google-workspace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfdude%2Fcomposio-google-workspace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfdude%2Fcomposio-google-workspace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfdude%2Fcomposio-google-workspace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cfdude","download_url":"https://codeload.github.com/cfdude/composio-google-workspace/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfdude%2Fcomposio-google-workspace/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272679261,"owners_count":24975253,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-29T02:00:10.610Z","response_time":87,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-29T11:43:24.856Z","updated_at":"2025-08-29T11:43:25.407Z","avatar_url":"https://github.com/cfdude.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Google Workspace MCP Service\n\nA 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.\n\n## 🚀 Features\n\n- **84 Custom Tools**: Complete Google Workspace API coverage (83 tools + 1 auth via Composio)\n- **MCP Service**: Persistent background service with PM2 process management\n- **Centralized Auth**: OAuth handled by Composio/Rube (no client secrets on desktops)\n- **TypeScript**: Full type safety with modern ES2022 features\n- **ES Modules**: Native ES module support throughout\n- **Auto-startup**: Configurable boot-time service activation\n- **Health Monitoring**: Built-in health endpoints for service monitoring\n- **PKCE Compliant**: Solves security compliance for remote workforce\n\n## 📋 Prerequisites\n\n- Node.js 18+ with npm\n- [Composio API Key](https://app.composio.dev/settings)\n- [Anthropic API Key](https://console.anthropic.com/) (optional, for AI features)\n- Google Workspace account for testing\n\n## 🛠️ Quick Start\n\n### 1. Installation\n\n```bash\n# Clone or download the project\ngit clone \u003crepository-url\u003e\ncd composio-google-workspace\n\n# Install dependencies\nnpm install\n```\n\n### 2. Environment Setup\n\n```bash\n# Copy environment template\ncp .env.example .env\n\n# Edit .env with your API keys\nCOMPOSIO_API_KEY=your_composio_api_key_here\nANTHROPIC_API_KEY=your_anthropic_api_key_here\n```\n\n### 3. Development\n\n```bash\n# Run in development mode\nnpm run dev\n\n# Or build and run\nnpm run build\nnpm start\n```\n\n## 🏗️ Project Structure\n\n```\nsrc/\n├── agents/                    # AI agent implementations\n│   └── google-workspace-agent.ts\n├── tools/                     # Custom tool definitions\n│   └── custom-tools.ts\n├── composio-client.ts         # Composio SDK initialization\n└── index.ts                   # Main application entry\n```\n\n## 🤖 Google Workspace Agent\n\nThe `GoogleWorkspaceAgent` class provides high-level methods for common workspace tasks:\n\n```typescript\nimport { GoogleWorkspaceAgent } from './src/agents/google-workspace-agent.js'\n\nconst agent = new GoogleWorkspaceAgent('user-123')\nawait agent.initialize(['gmail', 'googlecalendar'])\n\n// Send emails\nawait agent.sendEmail('colleague@company.com', 'Project Update', 'Here is the status...')\n\n// Create calendar events  \nawait agent.createCalendarEvent({\n  title: 'Team Standup',\n  start: '2024-01-15T09:00:00Z',\n  end: '2024-01-15T09:30:00Z',\n  attendees: ['team@company.com']\n})\n\n// Complex workflows\nawait agent.scheduleMeetingWithInvites({\n  title: 'Q1 Planning',\n  start: '2024-01-20T14:00:00Z', \n  end: '2024-01-20T15:00:00Z',\n  attendees: ['stakeholder1@company.com', 'stakeholder2@company.com'],\n  agenda: 'Q1 objectives and resource allocation'\n})\n```\n\n## 🔧 Custom Tools\n\nCreate specialized tools for your workspace needs:\n\n```typescript\nimport { initializeCustomTools } from './src/tools/custom-tools.js'\n\n// Initialize all custom tools\nconst tools = await initializeCustomTools()\n\n// Available custom tools:\n// - EMAIL_ANALYTICS: Analyze email patterns\n// - MEETING_OPTIMIZER: Find optimal meeting times  \n// - DOCUMENT_INTELLIGENCE: Extract insights from documents\n// - WORKSPACE_WORKFLOW: Automate cross-app workflows\n```\n\n## 🔐 Authentication Flow\n\n### Option 1: Interactive Setup\n\n```typescript\nimport { setupAuthentication, waitForAuthentication } from './src/composio-client.js'\n\n// Setup Gmail authentication\nconst connectionRequest = await setupAuthentication('user-123', 'gmail')\nconsole.log('Visit this URL:', connectionRequest.redirectUrl)\n\n// Wait for user to complete OAuth flow\nconst connectedAccount = await waitForAuthentication(connectionRequest.id)\nconsole.log('Gmail connected:', connectedAccount.id)\n```\n\n### Option 2: Pre-configured Connections\n\nConfigure connections via the [Composio Dashboard](https://app.composio.dev) and reference them by ID.\n\n## 📚 Available Scripts\n\n```bash\n# Development\nnpm run dev          # Start development server\nnpm run build        # Build for production\nnpm run preview      # Preview production build\nnpm start           # Run built application\n\n# Code Quality\nnpm run typecheck   # TypeScript type checking\nnpm run lint        # ESLint code linting\nnpm run lint:fix    # Fix ESLint issues automatically\nnpm run format      # Format code with Prettier\nnpm run format:check # Check code formatting\n```\n\n## 🔗 Integration Examples\n\n### Gmail Integration\n\n```typescript\n// Fetch recent emails\nconst emails = await agent.getRecentEmails(10, 'is:unread')\n\n// Send email with attachments\nawait agent.sendEmail('client@company.com', 'Proposal', 'Please find attached...', {\n  attachments: ['path/to/proposal.pdf']\n})\n```\n\n### Calendar Integration\n\n```typescript\n// Get upcoming events\nconst events = await agent.getUpcomingEvents(5)\n\n// Create recurring meeting\nawait agent.createCalendarEvent({\n  title: 'Weekly Sync',\n  start: '2024-01-15T10:00:00Z',\n  end: '2024-01-15T10:30:00Z',\n  recurrence: ['RRULE:FREQ=WEEKLY;BYDAY=MO']\n})\n```\n\n### Google Drive Integration\n\n```typescript\n// Upload documents\nawait agent.uploadToDrive('report.md', reportContent)\n\n// Search files\nconst files = await agent.searchDriveFiles('type:document modified:2024')\n```\n\n## 🚀 Advanced Workflows\n\n### Daily Summary Generation\n\n```typescript\n// Generate comprehensive daily summary\nconst summary = await agent.generateDailySummary('2024-01-15')\nconsole.log(summary)\n// Includes email activity, calendar events, and insights\n```\n\n### Meeting Orchestration\n\n```typescript\n// Complete meeting workflow: schedule + invites + follow-up\nawait agent.scheduleMeetingWithInvites({\n  title: 'Product Review',\n  start: '2024-01-20T15:00:00Z',\n  end: '2024-01-20T16:00:00Z', \n  attendees: ['product@company.com', 'engineering@company.com'],\n  agenda: 'Q1 product roadmap review and prioritization',\n  location: 'Conference Room A'\n})\n```\n\n## 🛡️ Error Handling\n\nThe project includes comprehensive error handling:\n\n```typescript\ntry {\n  await agent.sendEmail('invalid-email', 'Test', 'Body')\n} catch (error) {\n  console.error('Email failed:', error.message)\n  // Handle specific error cases\n}\n```\n\n## 📖 API Reference\n\n### Composio Client\n\n- `initializeComposio()` - Initialize SDK connection\n- `getAvailableTools(toolkits, userId)` - List available tools\n- `setupAuthentication(userId, toolkit)` - Start OAuth flow\n- `waitForAuthentication(requestId)` - Wait for auth completion\n- `executeTool(toolSlug, userId, arguments)` - Execute any tool\n\n### Google Workspace Agent\n\n- `initialize(services)` - Setup agent with required services\n- `sendEmail()` - Send emails with attachments\n- `getRecentEmails()` - Fetch and filter emails\n- `createCalendarEvent()` - Create calendar events\n- `getUpcomingEvents()` - List upcoming events\n- `uploadToDrive()` - Upload files to Drive\n- `searchDriveFiles()` - Search Drive content\n- `generateDailySummary()` - Generate daily activity summary\n\n## 🔧 Configuration\n\n### TypeScript Configuration\n\nThe project uses modern TypeScript settings in `tsconfig.json`:\n\n- Target: ES2022\n- Module: ESNext\n- Strict mode enabled\n- Path aliases supported (`@/` → `src/`)\n\n### Vite Configuration\n\nOptimized for Node.js development:\n\n- ES modules output\n- Source maps enabled\n- Proper external handling\n- Path alias resolution\n\n### Code Quality\n\n- **ESLint**: TypeScript-aware linting with recommended rules\n- **Prettier**: Consistent code formatting\n- **Pre-commit hooks**: Automated formatting and linting\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Make your changes and add tests\n4. Run quality checks: `npm run lint \u0026\u0026 npm run typecheck`\n5. Commit your changes: `git commit -m 'Add amazing feature'`\n6. Push to the branch: `git push origin feature/amazing-feature`\n7. Open a Pull Request\n\n## 📄 License\n\nThis project is licensed under the ISC License. See the LICENSE file for details.\n\n## 🆘 Troubleshooting\n\n### Common Issues\n\n**Authentication Errors**\n```bash\n# Verify API keys are set\nnpm run dev\n# Check console for authentication status\n```\n\n**TypeScript Errors**\n```bash\n# Run type checking\nnpm run typecheck\n\n# Check for missing dependencies\nnpm install\n```\n\n**Build Issues**\n```bash\n# Clear cache and rebuild\nrm -rf dist node_modules\nnpm install\nnpm run build\n```\n\n### Getting Help\n\n- [Composio Documentation](https://docs.composio.dev)\n- [Composio Discord Community](https://discord.com/invite/composio)\n- [GitHub Issues](https://github.com/composiohq/composio/issues)\n\n## 🔮 What's Next?\n\n- Add Anthropic Claude integration for AI-powered email responses\n- Implement workflow scheduling and automation\n- Add support for Google Sheets data processing\n- Create dashboard for monitoring agent activities\n- Add unit tests and CI/CD pipeline\n\n---\n\nBuilt with ❤️ using [Composio.dev](https://composio.dev) - The platform for AI agents to take actions in the real world.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcfdude%2Fcomposio-google-workspace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcfdude%2Fcomposio-google-workspace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcfdude%2Fcomposio-google-workspace/lists"}