systemprompt-mcp-google
Website | Documentation | Blog
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
Prerequisites
Before using this server, you'll need:
- A Systemprompt API key (free):
- An MCP-compatible client like:
- 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
- Create a project in Google Cloud Console
- Enable the APIs you need:
- Gmail API (read, send, compose, modify, labels)
- Google Calendar API (read events)
- Google Drive API (read-only)
- 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
- Install the package:
npm install systemprompt-mcp-google
- Create the credentials directory:
- Run the authentication script:
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
- Install and configure the client following its setup instructions
- In the client's MCP configuration, add this server:
{
"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.
Using Claude Desktop
- Install Claude Desktop
- Add this server in Claude's MCP configuration section with the API key:
{
"command": "SYSTEMPROMPT_API_KEY=your_api_key npx systemprompt-mcp-google"
}
- 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
- Set up Google Cloud Project and OAuth2 credentials:
- Create a project in Google Cloud Console
- Enable Gmail and Calendar APIs
- Create OAuth2 credentials
- Download credentials file
- Configure environment variables:
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
GOOGLE_REDIRECT_URI=your_redirect_uri
- Run the authentication script:
Usage
Through MCP Client
Once configured, you can use any MCP client to send commands to this server. Example interactions:
Gmail Operations
// 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
// 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:
# 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:
- Use the MCP Inspector:
- Enable debug logging:
# Set environment variable
DEBUG=mcp:* npm run dev
- Use the provided test client:
License
MIT
Development
Local Development Setup
- Clone the repository:
git clone https://github.com/yourusername/systemprompt-mcp-google.git
cd systemprompt-mcp-google
- Install dependencies:
- Set up environment variables:
# Copy example environment file
cp .env.example .env
# Edit .env and add:
SYSTEMPROMPT_API_KEY=your_api_key # Required - get from systemprompt.io/console
- Set up Google credentials:
- Save your Google OAuth credentials as
credentials/google-credentials.json - Run
npm run auth-google to authenticate with Google
- Start development server: