Health Reminder MCP

🚀 Health Reminder MCP System

A health reminder system based on the Model Context Protocol (MCP) that can pop up system notifications at regular intervals to remind you to get up and move, protecting your health.

✨ Features

• 🔔 Scheduled Reminders: Pop up system notifications at specified intervals (default is 30 minutes).
• ⚙️ Custom Configuration: Support customizing reminder intervals, message content, notification titles, and reminder sounds.
• 📊 Status Monitoring: View the running status and configuration information of reminders in real-time.
• 🎯 Immediate Reminders: Support manually triggering immediate reminders.
• 🖥️ Cross-Platform: Support system notifications on Windows, macOS, and Linux.
• 🔌 MCP Architecture: A complete Client-Server architecture, easy to integrate and expand.

📦 Project Structure

health-reminder-mcp/
├── src/
│   ├── server/
│   │   └── index.ts          # MCP Server implementation
│   └── client/
│       └── index.ts          # MCP Client implementation
├── package.json              # Project configuration
├── tsconfig.json             # TypeScript configuration
└── README.md                 # Documentation

🚀 Quick Start

1. Install Dependencies

npm install

2. Compile the Project

npm run build

3. Running Modes

Mode 1: Run the Client (Recommended)

The Client will automatically connect to the Server and provide an interactive console:

npm run client

Mode 2: Run the Server and Client Separately

Terminal 1 - Start the Server:

npm run server

Terminal 2 - Start the Client:

npm run client

4. Development Mode

# Start the Server (Development Mode)
npm run dev:server

# Start the Client (Development Mode)
npm run dev:client

💡 Usage Instructions

Interactive Console

After starting the Client, you will see the following menu:

╔════════════════════════════════════╗
║     Health Reminder MCP Client Console     ║
╠════════════════════════════════════╣
║  1. Start Health Reminder (Default 30 minutes)     ║
║  2. Start Health Reminder (Custom Configuration)     ║
║  3. Stop Health Reminder                   ║
║  4. View Current Status                   ║
║  5. Send an Immediate Reminder                   ║
║  6. View Available Tools                   ║
║  0. Exit the Program                       ║
╚════════════════════════════════════╝

Available Tools (MCP Tools)

The MCP Server provides the following tools:

1. start_reminder

Start the health reminder timer. Parameters:

• interval (number): Reminder interval in minutes (default is 30).
• message (string): Reminder message content.
• title (string): Notification title (default is "Health Reminder").
• sound (boolean): Whether to play a reminder sound (default is true).

2. stop_reminder

Stop the health reminder timer.

3. get_status

Get the current status and configuration of the health reminder.

4. send_immediate_reminder

Send a health reminder notification immediately (does not affect the timer). Parameters:

• message (string): Reminder message content.
• title (string): Notification title.
• sound (boolean): Whether to play a reminder sound.

💻 Usage Examples

Example 1: Use Default Configuration (Remind every 30 minutes)

1. Run npm run client.
2. Select option 1.
3. The system will pop up a reminder notification every 30 minutes.

Example 2: Custom Configuration (Remind every hour with a custom message)

1. Run npm run client.
2. Select option 2.
3. Enter the interval time: 60.
4. Enter the title: Break Time.
5. Enter the message: You've been working for an hour. It's time to take a break!.
6. Select the reminder sound: y.

Example 3: Test the Notification Immediately

1. Run npm run client.
2. Select option 5.
3. The system will pop up a notification immediately.

⚙️ Customize Default Configuration

Three methods are supported to customize the default reminder time and message:

1. Configuration File (Recommended)

Edit config.json in the project root directory:

{
  "reminder": {
    "interval": 45,
    "message": "It's been 45 minutes. It's time to take a break!",
    "title": "Work Reminder",
    "sound": true
  }
}

2. Environment Variables

set REMINDER_INTERVAL=60
set REMINDER_MESSAGE=It's time to take a break!
npm run server

3. Pass Parameters When Calling

In Cursor: Start health reminder every 45 minutes. Configuration Priority: Call parameters > Environment variables > Configuration file > Built-in default values. For detailed configuration instructions, please refer to: Configuration Guide | Configuration Examples

🔧 Technical Stack

• TypeScript: A type-safe superset of JavaScript.
• Node.js: A JavaScript runtime environment.
• @modelcontextprotocol/sdk: The official MCP SDK.
• node-notifier: A cross-platform system notification library.

🔧 Configuration Instructions

Default Configuration

{
  interval: 30,           // 30 minutes
  message: "It's time to get up and move! Sitting for long periods is bad for your health. It is recommended to stand up and walk around.",
  title: "Health Reminder",
  sound: true            // Enable reminder sound
}

Custom Configuration

You can customize the configuration in the following ways:

1. Through the interactive menu: Select option 2 and enter the configuration as prompted.
2. Through MCP tool calls: Use the start_reminder tool and pass in parameters.

📱 System Notification Support

• Windows 10/11: Use the native notification center.
• macOS: Use the native notification center.
• Linux: Use libnotify (needs to be installed).

Install Notification Support on Linux

# Ubuntu/Debian
sudo apt-get install libnotify-bin

# Fedora
sudo dnf install libnotify

# Arch Linux
sudo pacman -S libnotify

📚 Documentation

Deployment Methods

• Deployment Guide - Understand the differences between different deployment methods.
• Publish to npm - 📦 Recommended! Share your MCP Server like chrome-devtools-mcp.
• Server Deployment - Cloud server deployment (for reference only, not recommended for this project).

Usage and Configuration

• Cursor Configuration Guide - Use MCP in Cursor.
• Configuration Instructions - Detailed configuration options.
• API Documentation - MCP tool interface documentation.
• Usage Tutorial - A complete usage tutorial.

🤝 Integration into Other Applications

Since the MCP protocol is used, you can easily integrate this health reminder system into any application that supports MCP:

1. Register the Server in the MCP configuration file.
2. Connect using any MCP Client.
3. Call the provided tools.

Share with Others

Want others to use your health reminder system? Check out the Publish to npm Guide.

📄 License

MIT License

🙏 Acknowledgments

• Model Context Protocol
• node-notifier

💪 Health Tips

• It is recommended to get up and move for 5 - 10 minutes every 30 minutes.
• You can do simple stretching exercises.
• Look out of the window to relax your eyes.
• Drink an appropriate amount of water to keep your body hydrated.
• Maintain a good sitting posture and avoid looking down for long periods.

May you have a pleasant experience and good health! 🌟