Code Snippet Server

# systemprompt-mcp-google [](https://www.npmjs.com/package/systemprompt-mcp-google) [](https://opensource.org/licenses/MIT) [](https://twitter.com/tyingshoelaces_) [](https://discord.com/invite/wkAbSuPWpr) [Website](https://systemprompt.io) | [Documentation](https://systemprompt.io/documentation) | [Blog](https://tyingshoelaces.com) A specialized Model Context Protocol (MCP) server that integrates Google services (Gmail, Calendar, etc.) into your AI workflows. This server enables seamless access to Google services through MCP, allowing AI agents to interact with Gmail, Google Calendar, and other Google services. ## Demo  [YouTube Demo](https://youtu.be/mC9QF6ewWJQ) ## Prerequisites Before using this server, you'll need: 1. A Systemprompt API key (free): - Sign up at [systemprompt.io/console](https://systemprompt.io/console) - Create a new API key - Required to run the server 2. An MCP-compatible client like: - [Systemprompt MCP Client](https://github.com/Ejb503/multimodal-mcp-client) - Claude Desktop - Or any other MCP-compatible client 3. Google Cloud Project setup: - A Google Cloud account - API access enabled for desired services (Gmail, Calendar, etc.) - OAuth2 credentials configured ## Setup ### 1. Google Cloud Setup 1. Create a project in [Google Cloud Console](https://console.cloud.google.com) 2. Enable the APIs you need: - Gmail API (read, send, compose, modify, labels) - Google Calendar API (read events) - Google Drive API (read-only) 3. Create OAuth2 credentials: - Go to "APIs & Services" > "Credentials" - Create an OAuth 2.0 Client ID - Set authorized redirect URIs (include `http://localhost:3333/oauth2callback`) - Download the credentials JSON file and save it as `credentials/google-credentials.json` ### 2. Server Configuration 1. Install the package: ```bash npm install systemprompt-mcp-google ``` 2. Create the credentials directory: ```bash mkdir -p credentials ``` 3. Run the authentication script: ```bash npm run auth-google ``` This will: - Open your default browser for Google OAuth authentication - Start a local server on port 3333 to handle the OAuth callback - Generate and save tokens to `credentials/google-token.json` - Close automatically once authentication is complete The script will request the following permissions: - Gmail: read, send, compose, modify, and manage labels - Calendar: read events and calendars - Drive: read-only access ### 3. MCP Client Setup Choose your preferred MCP client: #### Using Systemprompt MCP Client 1. Install and configure the client following its [setup instructions](https://github.com/Ejb503/multimodal-mcp-client#-getting-started) 2. In the client's MCP configuration, add this server: ```json { "servers": { "google": { "type": "stdio", "command": "SYSTEMPROMPT_API_KEY=your_api_key npx systemprompt-mcp-google" } } } ``` Note: Replace `your_api_key` with your actual Systemprompt API key from [systemprompt.io/console](https://systemprompt.io/console). #### Using Claude Desktop 1. Install Claude Desktop 2. Add this server in Claude's MCP configuration section with the API key: ```json { "command": "SYSTEMPROMPT_API_KEY=your_api_key npx systemprompt-mcp-google" } ``` 3. Configure the connection to use stdio mode ## Features ### Google Service Integration - **Gmail Integration** - Read and send emails through MCP commands - Manage drafts and attachments - Search and filter emails - Handle email threads - **Calendar Integration** - Create and manage events through MCP commands - Handle event invitations - Search and filter calendar events - Manage multiple calendars ### MCP Integration - **Standard MCP Interface** - Compatible with any MCP-compliant client - Structured command responses - Error handling and status reporting - Session management ### Security & Authentication - Secure OAuth2 authentication flow - Automatic token refresh - Scoped access for different services - Environment-based configuration ### Development Features - Full TypeScript support - Comprehensive error handling - Extensive test coverage - MCP-compatible interface ### Configuration 1. Set up Google Cloud Project and OAuth2 credentials: - Create a project in [Google Cloud Console](https://console.cloud.google.com) - Enable Gmail and Calendar APIs - Create OAuth2 credentials - Download credentials file 2. Configure environment variables: ```env GOOGLE_CLIENT_ID=your_client_id GOOGLE_CLIENT_SECRET=your_client_secret GOOGLE_REDIRECT_URI=your_redirect_uri ``` 3. Run the authentication script: ```bash npm run auth-google ``` ## Usage ### Through MCP Client Once configured, you can use any MCP client to send commands to this server. Example interactions: #### Gmail Operations ```typescript // Example MCP command structure for sending an email { "command": "gmail.sendEmail", "parameters": { "to": "recipient@example.com", "subject": "Hello from MCP", "body": "This email was sent via MCP!" } } // Example MCP command for listing messages { "command": "gmail.listMessages", "parameters": { "maxResults": 10 } } ``` #### Calendar Operations ```typescript // Example MCP command for creating an event { "command": "calendar.createEvent", "parameters": { "summary": "Team Meeting", "start": "2024-03-01T10:00:00", "end": "2024-03-01T11:00:00", "attendees": ["team@company.com"] } } // Example MCP command for listing events { "command": "calendar.listEvents", "parameters": { "timeMin": "2024-03-01T00:00:00Z", "maxResults": 10 } } ``` ### Testing The project includes comprehensive tests for both MCP protocol handling and Google service integration: ```bash # Run all tests npm test # Watch mode for development npm run test:watch # Generate coverage report npm run test:coverage ``` ### Debugging MCP Communication Since MCP servers communicate over stdio, debugging requires special consideration: 1. Use the MCP Inspector: ```bash npm run inspector ``` 2. Enable debug logging: ```bash # Set environment variable DEBUG=mcp:* npm run dev ``` 3. Use the provided test client: ```bash npm run test:client ``` ## License MIT ## Related Projects - [Model Context Protocol](https://github.com/modelcontextprotocol/protocol) - [Systemprompt MCP Client](https://github.com/Ejb503/multimodal-mcp-client) - [MCP Inspector](https://github.com/modelcontextprotocol/inspector) ## Development ### Local Development Setup 1. Clone the repository: ```bash git clone https://github.com/yourusername/systemprompt-mcp-google.git cd systemprompt-mcp-google ``` 2. Install dependencies: ```bash npm install ``` 3. Set up environment variables: ```bash # Copy example environment file cp .env.example .env # Edit .env and add: SYSTEMPROMPT_API_KEY=your_api_key # Required - get from systemprompt.io/console ``` 4. Set up Google credentials: - Save your Google OAuth credentials as `credentials/google-credentials.json` - Run `npm run auth-google` to authenticate with Google 5. Start development server: ```bash npm run dev ```