Google Workspace

🚀 Google Workspace MCP

This project provides a convenient way to interact with Google Workspace services, including account management, email handling, and calendar operations.

🚀 Quick Start

📦 Installation

npm install google-workspace-mcp --save

⚙️ Configuration

Account Manager Instance

import { AccountManager } from 'google-workspace-mcp';

const accountManager = new AccountManager({
  configPath: './config',
  scopes: ['https://www.googleapis.com/auth/gmail.readonly']
});

Default Configuration Path

• Windows: C:\Users\<CurrentUser>\.mcp\google-workspace-mcp
• macOS/Linux: ~/.mcp/google-workspace-mcp

✨ Features

👤 Account Operations

await accountManager.authenticate('user123', {
  type: 'password',
  credentials: {
    username: 'your_username',
    password: 'your_password'
  }
});

📧 Email Handling

const gmail = accountManager.getGmailService('user123');
const inbox = await gmail.inbox.list();

📅 Calendar Operations

const calendar = accountManager.getCalendarService('user123');
const events = await calendar.calendar.events.list('primary');

💻 Usage Examples

Basic Usage

// Account authentication
await accountManager.authenticate('user123', {
  type: 'password',
  credentials: {
    username: 'your_username',
    password: 'your_password'
  }
});

// Get Gmail inbox
const gmail = accountManager.getGmailService('user123');
const inbox = await gmail.inbox.list();

// Get calendar events
const calendar = accountManager.getCalendarService('user123');
const events = await calendar.calendar.events.list('primary');

📚 Documentation

For detailed information, please refer to the API Documentation.

🚧 Future Plans

New Services

• Support for Admin SDK
• Integration with other Google services

🧪 Testing Strategy

Unit Testing Methods

1. Simplified Mocking

   • Use static mock responses to ensure test predictability.
   • Avoid complex end - to - end simulations in unit tests.
   • Test only one functional module at a time.
   • Use simple implementations for external dependencies (e.g., OAuth, file system).

2. Test Organization

   • Group tests by functionality (e.g., account operations, file operations).
   • Use clear and descriptive test names.
   • Keep tests focused and isolated.
   • Reset mocks and modules between each test.

3. Mock Management

   • Use jest.resetModules() to ensure a clean state.
   • Reload modules after mock modifications.
   • Explicitly track mock function calls.
   • Verify both function calls and results.

4. File System Testing

   • Use simple JSON structures.
   • Focus on data correctness rather than format.
   • Test error scenarios (e.g., missing files, invalid JSON).
   • Verify file operations without knowing implementation details.

5. Token Handling

   • Use static responses to simulate token verification.
   • Test both success and failure scenarios separately.
   • Ignore OAuth complexity and focus on the account manager's token handling logic.

Running Tests

# Run all tests
npm test

# Run a specific test file
npm test path/to/test.ts

# Run tests with coverage
npm test -- --coverage

# Run all tests with coverage in CI build
npm run test:ci

💡 Best Practices

Authentication

• Securely store credentials in MCP settings.
• Use the minimum required permission scope.
• Properly handle token refresh.

Error Handling

• Check response status codes.
• Handle authentication errors appropriately.
• Establish a complete logging mechanism.

Configuration Management

• Avoid exposing credentials in the production environment.
• Regularly update API keys.
• Use environment variables to manage sensitive information.

Performance Optimization

• Set reasonable request timeout times.
• Implement rate limiting to prevent overload.
• Use caching to reduce API requests.

🔗 Project Links

• GitHub: https://github.com/yourusername/google-workspace-mcp
• npm: https://www.npmjs.com/package/google-workspace-mcp

📄 License

This project is licensed under the MIT License.