Skip to main content
Glama
MCP Reminder

MCP Reminder

by sheacoding

小智MCP闹钟和待办事项服务

为小智AI提供闹钟和待办事项管理功能的MCP服务。

版本说明

🎉 V2 主动通知版本已发布!

  • V2 (当前默认): 支持资源订阅和主动通知,后台自动检查到期提醒

  • V1 (稳定版): 仅被动响应,需要客户端主动调用工具

详细测试指南请查看: V2_TEST_GUIDE.md

Related MCP server: nudge

功能特性

  • 语音设定闹钟,到点提醒

  • 语音添加待办事项,设置提醒时间

  • 语音完成待办,自动更新状态

  • 支持自然语言时间解析(如"明天下午3点"、"30分钟后")

  • 数据持久化存储

  • ✨ V2新增: Resource订阅机制,支持主动推送通知

安装

1. 克隆或下载项目

cd mcp-reminder

2. 安装依赖

项目使用UV管理依赖:

uv sync

使用方法

快速启动(推荐)

项目已包含 mcp_pipe.py 和启动脚本,开箱即用。默认启动V2版本(支持主动通知)。

Linux/Mac:

chmod +x start.sh
./start.sh

Windows PowerShell (推荐):

.\start.ps1

如果提示无法运行脚本,先执行:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Windows CMD:

start.bat

⚠️ Windows用户注意:

  • 推荐使用PowerShell运行 .\start.ps1

  • 不要在PowerShell中运行.bat文件(会出现编码问题)

  • 详细的Windows启动说明请查看: WINDOWS_SETUP.md

这将自动连接到配置好的小智MCP接入点并启动服务。

手动启动

如需自定义配置,可以手动设置环境变量:

Linux/Mac:

export MCP_ENDPOINT="wss://api.xiaozhi.me/mcp/?token=YOUR_TOKEN"
uv run python mcp_pipe.py run_server.py

Windows (PowerShell):

$env:MCP_ENDPOINT = "wss://api.xiaozhi.me/mcp/?token=YOUR_TOKEN"
uv run python mcp_pipe.py run_server.py

Windows (CMD):

set MCP_ENDPOINT=wss://api.xiaozhi.me/mcp/?token=YOUR_TOKEN
uv run python mcp_pipe.py run_server.py

使用配置文件(可选)

复制配置文件模板:

cp mcp_config.json.example mcp_config.json

编辑 mcp_config.json 自定义配置,然后运行:

export MCP_ENDPOINT="wss://api.xiaozhi.me/mcp/?token=YOUR_TOKEN"
uv run python mcp_pipe.py

本地测试(stdio模式)

用于本地测试MCP工具功能(不连接小智):

uv run python -m mcp_reminder.server

然后可以使用MCP Inspector或其他MCP客户端连接测试。

MCP工具说明

闹钟管理

add_alarm - 添加闹钟

设置一个闹钟。

参数:

  • time (必填): 闹钟时间,支持自然语言

    • 示例: "下午2点30分"、"明天上午10点"、"2025-09-02 14:30"

  • description (可选): 闹钟描述

示例:

语音:"小智,帮我设置一个下午2点30分的闹钟"
语音:"小智,明天上午9点提醒我开会"

get_pending_alarms - 查询到期闹钟

获取所有已到期且未关闭的闹钟(小智会定期自动调用)。

dismiss_alarm - 关闭闹钟

关闭指定的闹钟。

参数:

  • alarm_id (必填): 闹钟ID

待办事项管理

add_todo - 添加待办事项

创建一个新的待办事项。

参数:

  • title (必填): 待办事项标题

  • remind_time (可选): 提醒时间,支持自然语言

  • description (可选): 待办事项描述

示例:

语音:"小智,提醒我明天下午3点完成项目文档"
语音:"小智,添加待办:给客户发送报价单"

get_pending_todos - 查询到期待办

获取所有到期且未完成的待办事项(小智会定期自动调用)。

complete_todo - 完成待办

标记待办事项为已完成,支持通过标题模糊匹配。

参数:

  • title (必填): 待办事项标题或关键词

示例:

语音:"小智,我已经完成项目文档了"
语音:"小智,报价单发完了"

list_todos - 列出待办事项

查看所有待办事项。

参数:

  • status (可选): 筛选状态

    • "pending": 未完成(默认)

    • "completed": 已完成

    • "all": 全部

示例:

语音:"小智,我有哪些待办事项"
语音:"小智,列出所有已完成的任务"

综合查询

check_all_reminders - 检查所有提醒(新增)✨

一次性检查所有到期的闹钟和待办事项。

重要:提醒机制说明

  • MCP服务是被动响应的,不能主动推送提醒

  • 需要小智AI定期调用此工具来检查是否有到期项

  • 建议配置每1分钟自动调用一次

参数:

  • 无

返回:

  • 所有到期的闹钟和待办列表

  • 提醒消息列表(可直接语音播报)

示例:

语音:"小智,检查一下有没有到期的提醒"
语音:"小智,看看有什么要提醒我的"

详细说明请查看: REMINDER_MECHANISM.md

数据存储

数据以JSON格式存储在 data/ 目录下:

  • data/alarms.json - 闹钟数据

  • data/todos.json - 待办事项数据

开发说明

项目结构

mcp-reminder/
├── src/mcp_reminder/
│   ├── __init__.py
│   ├── models.py      # 数据模型
│   ├── storage.py     # JSON持久化
│   └── server.py      # MCP服务入口
├── data/              # 数据存储目录
├── pyproject.toml     # UV项目配置
└── README.md

运行测试

添加测试数据:

# 在Python REPL中测试
uv run python
from mcp_reminder.storage import JSONStorage
from mcp_reminder.models import Alarm, Todo, parse_time

storage = JSONStorage()

# 添加闹钟
alarm = Alarm(time=parse_time("2分钟后"), description="测试闹钟")
storage.add_alarm(alarm)

# 添加待办
todo = Todo(title="测试待办", remind_time=parse_time("1分钟后"))
storage.add_todo(todo)

扩展功能

未来可以考虑添加:

  • 重复闹钟(每天/每周)

  • 待办事项分类和标签

  • 优先级设置

  • 数据导出/导入

许可

MIT License

Available Tools

8 tools
add_alarmB

添加闹钟

Args: time: 闹钟时间,支持自然语言如"下午2点30分"、"明天上午10点"或精确时间"2025-09-02 14:30" description: 闹钟描述(可选)

Returns: 包含闹钟ID和确认信息的字典

Inputs: time (required), description.

add_todoB

添加待办事项

Args: title: 待办事项标题 remind_time: 提醒时间(可选),支持自然语言如"明天下午3点" description: 待办事项描述(可选)

Returns: 包含待办ID和确认信息的字典

Inputs: title (required), remind_time, description.

check_all_remindersB

一次性检查所有到期的提醒(闹钟和待办事项)

这是一个便捷工具,小智可以定期调用此接口来检查是否有需要提醒的内容

Returns: 包含所有到期闹钟和待办的汇总信息

Inputs: no named parameters.

complete_todoC

完成待办事项

通过标题关键词匹配待办事项并标记为已完成

Args: title: 待办事项标题或关键词

Returns: 操作结果

Inputs: title (required).

dismiss_alarmC

关闭/删除闹钟

Args: alarm_id: 闹钟ID

Returns: 操作结果

Inputs: alarm_id (required).

get_pending_alarmsB

获取所有到期的闹钟

小智会定期调用此接口检查是否有需要提醒的闹钟

Returns: 包含到期闹钟列表的字典

Inputs: no named parameters.

get_pending_todosC

获取所有到期且未完成的待办事项

小智会定期调用此接口检查是否有需要提醒的待办

Returns: 包含到期待办列表的字典

Inputs: no named parameters.

list_todosB

列出待办事项

Args: status: 筛选状态,可选值: "pending"(未完成)、"completed"(已完成)、"all"(全部),默认"pending"

Returns: 待办事项列表

Inputs: status.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 8 tools

    Disambiguation4/5

    Most tools have distinct purposes, but there is some overlap between 'check_all_reminders' and the individual 'get_pending_alarms' and 'get_pending_todos' tools, which could cause confusion about when to use each. However, descriptions clarify that 'check_all_reminders' is a convenience tool for periodic checks, while the others are more specific.

    Naming Consistency4/5

    Tool names follow a consistent verb_noun pattern (e.g., 'add_alarm', 'complete_todo'), with only minor deviations like 'check_all_reminders' using a plural noun and 'list_todos' being slightly less descriptive. Overall, the naming is predictable and readable.

    Tool Count5/5

    With 8 tools, the count is well-scoped for a reminder management server, covering core operations like adding, completing, listing, and dismissing reminders without being overwhelming. Each tool serves a clear purpose in the domain.

    Completeness4/5

    The tool set provides good coverage for reminder management, including add, complete, list, and dismiss operations for both alarms and todos. A minor gap is the lack of a tool to update existing reminders (e.g., modify alarm time or todo details), but agents can work around this by dismissing and re-adding.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      F
      maintenance
      An MCP server that allows AI assistants to manage todo lists stored in a simple markdown file, supporting creation, reading, updating, and deletion of todo items with persistent IDs.
      5
      16 npm
      6
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that connects AI assistants like Claude to your todo app, enabling natural, friendly reminders and task management without a server to run.
      8
      11 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for managing structured reminders for AI agents, with persistent storage, full-text search, and cross-session support.
      8 npm
      1
      MIT