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):
- Sign up at systemprompt.io/console
- Create a new API key
- Required to run the server
An MCP-compatible client like:
- Systemprompt MCP Client
- Claude Desktop
- Or any other MCP-compatible client
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:

mkdir -p credentials

Run the authentication script:

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

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:

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

// 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:

npm run inspector

Enable debug logging:

# Set environment variable
DEBUG=mcp:* npm run dev

Use the provided test client:

npm run 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:

npm install

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:

npm run dev