Uses .env files for managing environment configuration including email credentials, Google Sheets settings, and scheduler parameters
Sends personalized email reminders to customers using Gmail SMTP with app password authentication and customizable message templates
Utilizes Google Cloud Console for managing service account credentials and API access permissions for Google Sheets integration
Reads customer reminder data from Google Sheets including customer names, emails, due dates, and message templates with support for multiple date formats
Implemented as a Python application using libraries like gspread, oauth2client, and apscheduler for Google Sheets integration and email automation
Stores APScheduler job data and tracks sent reminders to prevent duplicates using SQLite database
Customer Reminder MCP
A Model Context Protocol (MCP) server that helps business owners manage and automatically send customer reminders via email. This system integrates with Google Sheets to read customer data and sends scheduled reminders based on due dates.
Features
🚀 Google Sheets Integration
Connect to Google Sheets to read customer reminder data
Support for multiple date formats (YYYY-MM-DD, MM/DD/YYYY, DD/MM/YYYY)
Automatic data validation and error handling
📧 Email Reminders
Send personalized email reminders to customers
Customizable message templates with dynamic placeholders
Support for Gmail SMTP with app passwords
⏰ Intelligent Scheduling
APScheduler-based background processing
Configurable interval checking (minutes, hours, days)
Prevents duplicate reminder sends with tracking system
Immediate execution or scheduled background service
🔌 Model Context Protocol (MCP) Integration
Full MCP server implementation
Tools for checking reminders, sending reminders, and retrieving data
Resources for accessing customer reminders and sent reminder history
Test mode to verify sheet connection and server status
Project Structure
Prerequisites
Python 3.8+ installed
Google Sheets API credentials (service account JSON file)
Gmail account with app password enabled
Google Sheet with customer reminder data
Setup Instructions
1. Install Dependencies
Or install individually:
2. Set up Google Sheets API Credentials
Copy the provided example file:
cp credentials.example.json credentials.jsonReplace the placeholder values in
credentials.json
with your actual Google service account credentials.SECURITY WARNING: Never commit your
credentials.json
file to version control or share it publicly!
3. Create Environment File
Copy the provided example file:
cp .env.example .envEdit the
.env
file and update with your actual values:
4. Test Your Configuration
Test your connection to Google Sheets and verify the setup:
This will verify your connection and display the available MCP tools and resources.
3. Setup Google Sheets API
Go to Google Cloud Console
Create a new project or select existing
Enable Google Sheets API
Create service account credentials:
Navigate to "IAM & Admin" > "Service Accounts"
Click "Create Service Account"
Provide a name and description
For role, select a minimal role like "Viewer" or create a custom role with specific permissions
Create a key for the service account:
Select your new service account
Go to the "Keys" tab
Click "Add Key" > "Create new key"
Choose JSON format
Download the JSON credentials file and save it as
credentials.json
in your project directoryShare your Google Sheet with the service account email address (limited to "Viewer" or "Editor" as needed)
IMPORTANT: Keep your credentials secure:
Never commit this file to version control
Restrict access to the credentials file on your local system
Consider encrypting the file when not in use
4. Prepare Your Google Sheet
Create a Google Sheet with these columns:
customer_name
- Customer's full namecustomer_email
- Customer's email addressdue_date
- When reminder is due (YYYY-MM-DD format)message_template
- Custom message (use {customer_name} and {due_date} placeholders)reminder_type
- Set to "email"
Example:
customer_name | customer_email | due_date | message_template | reminder_type |
John Doe | 2025-08-15 | Hi {customer_name}! Your appointment is on {due_date}. |
Usage
Run Once (Immediate)
Start Scheduler (Background Service)
Run MCP Server
Help
How It Works
Data Source: Reads customer data from Google Sheets
Date Checking: Identifies reminders due today or overdue
Duplicate Prevention: Tracks sent reminders to prevent duplicates
Email Sending: Sends personalized emails via SMTP
Scheduling: Runs automatically at specified intervals
Logging: Provides detailed console output for monitoring
MCP Integration: Exposes functionality via Model Context Protocol
Scheduler Settings
DEFAULT_INTERVAL_MINUTES: Default check interval (default: 6)
MCP Server Tools
The MCP server exposes the following tools:
send_reminder: Sends a single reminder to a customer
check_due_reminders: Checks for and sends all due reminders
get_customer_reminders: Retrieves customer reminder data
get_sent_reminders: Retrieves history of sent reminders
get_sheet_status: Checks connection status with Google Sheets
MCP Server Resources
reminders://customer-reminders: Customer reminder data
reminders://sent-reminders: History of sent reminders
Troubleshooting
Common Issues
Gmail Authentication Error (535)
Ensure 2-Step Verification is enabled
Use app password, not regular password
Check username/password in .env file
Google Sheets Not Found
Verify spreadsheet name matches exactly
Ensure service account has access to the sheet
Check credentials.json file exists
No Reminders Found
Verify date format in Google Sheet (YYYY-MM-DD)
Check if reminders are due (today or overdue)
Ensure required columns exist with correct names
Development
Testing
Use short intervals for testing:
Test the MCP server functionality:
This will show:
Available tools and resources
Example tool calls
Google Sheets connection status
Current reminders in the system
Adding Features
The modular design allows easy extension:
Add new reminder types (SMS, etc.)
Integrate with different data sources
Add web dashboard
Implement advanced scheduling
Create new MCP tools and resources
License
This project is part of the Model Context Protocol ecosystem and is designed for business automation and customer relationship management for Preshify.
Security Best Practices
Protecting Sensitive Information
Never commit credentials to version control
Both
credentials.json
and.env
files contain sensitive informationAlways keep these files in your
.gitignore
Use example files (provided) to show the structure without exposing real data
Regularly rotate credentials
Periodically generate new Google service account keys
Update your Gmail app password regularly
Revoke unused or potentially compromised credentials
Limit permissions
Your Google service account should have minimal required permissions
Share your Google Sheet with the service account email using the most restrictive permissions necessary
Monitor for unauthorized access
Regularly check the Google Cloud Console for unusual activity
Review application logs for unexpected behavior
Be alert to unplanned or unexpected emails being sent
Data Handling Recommendations
Minimize data retention
Only store the customer data you need
Consider implementing a data retention policy
Regularly clean up old reminder data
Implement logging best practices
Don't log sensitive customer information
Use log rotation to prevent log files from growing too large
Regularly review logs for security issues
Support
For issues, questions, or feature requests, please create an issue in the repository.
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Enables automated customer reminder management by connecting to Google Sheets to read customer data and sending personalized email reminders based on due dates. Provides intelligent scheduling with duplicate prevention and integrates with Gmail SMTP for business automation.
Related MCP Servers
- -securityAlicense-qualityIntegration server that enables interaction with Google services including Gmail and Calendar, allowing users to manage emails, draft responses, and schedule events across multiple Google accounts.Last updated -3MIT License
- AsecurityAlicenseAqualityManage your emails effortlessly with a standardized interface for drafting, sending, retrieving, and organizing messages. Streamline your email workflow with complete Gmail API coverage, including label and thread management.Last updated -6410934MIT License
- -securityFlicense-qualityEnables programmatic management of Google Calendar events through natural language interactions, supporting creation, reading, updating, and deletion of events with features for recurring events, attendees, and reminders.Last updated -2
- AsecurityAlicenseAqualityProvides comprehensive Google Calendar integration capabilities allowing AI assistants to list, create, update, and delete calendar events through a standardized Model Context Protocol.Last updated -56MIT License