systemprompt-mcp-google

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:

1. A Systemprompt API key (free):

   • Sign up at systemprompt.io/console
   • Create a new API key
   • Required to run the server

2. An MCP-compatible client like:

   • Systemprompt 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
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:

npm install systemprompt-mcp-google

2. Create the credentials directory:

mkdir -p credentials

3. 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

1. Install and configure the client following its setup instructions
2. 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

1. Install Claude Desktop
2. Add this server in Claude's MCP configuration section with the API key:

   {
     "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
   • Enable Gmail and Calendar APIs
   • Create OAuth2 credentials
   • Download credentials file

2. Configure environment variables:

GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
GOOGLE_REDIRECT_URI=your_redirect_uri

3. 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:

1. Use the MCP Inspector:

npm run inspector

2. Enable debug logging:

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

3. Use the provided test client:

npm run test:client

License

MIT

Related Projects

• Model Context Protocol
• Systemprompt MCP Client
• MCP Inspector

Development

Local Development Setup

1. Clone the repository:

git clone https://github.com/yourusername/systemprompt-mcp-google.git
cd systemprompt-mcp-google

2. Install dependencies:

npm install

3. 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

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:

npm run dev