npm package: @gongcishi/remind-mcp-server
Description: MCP server for Gongcishi Remind - Create WeChat reminder notifications through AI agents
Author: Gongcishi Team
Latest version: 1.2.0

# 共此时提醒 MCP 服务器

[![npm version](https://badge.fury.io/js/@gongcishi%2Fremind-mcp-server.svg)](https://www.npmjs.com/package/@gongcishi/remind-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[English](README.md) | 简体中文

一个用于共此时提醒系统的 MCP (Model Context Protocol) 服务器，让 AI Agent（如 Claude）能够通过自然语言创建微信提醒通知。

## ✨ 功能特性

- 🤖 **AI Agent 集成**：通过 MCP 协议与 Claude Desktop、Cline 等 AI 工具无缝集成
- ⏰ **灵活的时间格式**：支持标准格式、相对时间、自然语言等多种时间表达方式
- 📱 **微信推送**：通过微信公众号向用户推送提醒消息
- 🔒 **安全认证**：使用 API Key 进行安全认证
- 📦 **开箱即用**：通过 npm 一键安装，无需额外配置
- 🌍 **标准协议**：完全遵循 MCP 标准，兼容所有 MCP 客户端

## 📦 安装

### 方式一：通过 npx 使用（推荐，无需安装）

```bash
# 在 Claude Desktop 配置中直接使用 npx
# 见下方配置示例
```

### 方式二：全局安装

```bash
npm install -g @gongcishi/remind-mcp-server
```

### 方式三：本地安装

```bash
npm install @gongcishi/remind-mcp-server
```

## 🚀 快速开始

### 步骤 1：获取 API Key

1. 打开**共此时提醒**小程序（微信搜索"共此时提醒"）
2. 进入"提醒能力开放平台"页面
3. 点击"创建"按钮，创建一个新的 API Key
4. 复制生成的 API Key（格式：`gcs_xxxxxx...`）

### 步骤 2：配置 Claude Desktop

找到并编辑 Claude Desktop 配置文件：

- **macOS/Linux**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

添加以下配置（推荐使用 npx 方式）：

```json
{
  "mcpServers": {
    "gongcishi-remind": {
      "command": "npx",
      "args": ["-y", "@gongcishi/remind-mcp-server"],
      "env": {
        "GONGCISHI_API_KEY": "gcs_your_api_key_here"
      }
    }
  }
}
```

如果已全局安装，也可以使用：

```json
{
  "mcpServers": {
    "gongcishi-remind": {
      "command": "gongcishi-remind-mcp",
      "env": {
        "GONGCISHI_API_KEY": "gcs_your_api_key_here"
      }
    }
  }
}
```

### 步骤 3：重启 Claude Desktop

**重要**：必须完全退出并重新启动 Claude Desktop

- **macOS**: 使用 `Cmd+Q` 或菜单栏选择"退出 Claude"
- **Windows**: 右键点击系统托盘中的 Claude 图标，选择"退出"

⚠️ 仅关闭窗口不会生效，必须完全退出应用！

### 步骤 4：开始使用

在 Claude Desktop 中，您可以使用自然语言创建提醒：

**示例对话**：

```
你：帮我创建一个提醒，明天下午3点开会

Claude：好的，我来帮你创建提醒。
[调用 create_wechat_remind 工具]
✅ 提醒创建成功！

📝 内容：明天下午3点开会
⏰ 提醒时间：明天 15:00
🆔 提醒ID：123456

系统将在指定时间通过微信公众号向您推送提醒消息。
```

**更多示例**：

- "提醒我后天早上9点去机场"
- "3小时后提醒我查看邮件"
- "设置一个提醒，下周一上午10点和下午2点分别提醒我"
- "明天中午12点提醒我吃药，这个很重要"

## ⏰ 支持的时间格式

| 格式类型 | 示例 | 说明 |
|---------|------|------|
| **标准格式** | `2024-12-01 15:00`<br>`2024-12-25 09:30` | 完整的日期时间 |
| **相对时间** | `3小时后`<br>`30分钟后`<br>`2天后` | 相对于当前时间 |
| **自然语言** | `明天 14:00`<br>`后天 10:00`<br>`下周一 09:00` | 中文自然语言 |

## 🔧 环境变量

| 变量名 | 必需 | 默认值 | 说明 |
|--------|------|--------|------|
| `GONGCISHI_API_KEY` | ✅ | - | 共此时提醒 API Key（必填） |
| `GONGCISHI_API_URL` | ❌ | `https://remind.gongcishi.cn` | API 服务器地址（可选） |

## 🛠️ 开发指南

### 克隆仓库

```bash
git clone https://github.com/gongcishi/remind-mcp-server.git
cd remind-mcp-server
```

### 安装依赖

```bash
npm install
```

### 构建项目

```bash
npm run build
```

### 本地调试

使用 MCP Inspector 进行调试：

```bash
npm run inspector
```

### 监听文件变化

```bash
npm run watch
```

## 🐛 故障排查

### 问题 1：工具未在 Claude Desktop 中显示

**解决方案**：

1. 检查 `claude_desktop_config.json` 文件语法是否正确（JSON 格式）
2. 确认 API Key 已正确设置在 `env.GONGCISHI_API_KEY` 中
3. **完全退出**并重启 Claude Desktop（不是关闭窗口）
4. 查看 Claude Desktop 日志文件：
   ```bash
   # macOS/Linux
   tail -f ~/Library/Logs/Claude/mcp*.log
   ```

### 问题 2：创建提醒失败

**可能原因**：

1. ❌ API Key 无效或已过期
2. ❌ 时间格式不正确
3. ❌ 网络连接问题
4. ❌ API 调用次数超限（每天最多 100 次）

**解决方案**：

1. 在小程序中检查 API Key 是否有效
2. 使用支持的时间格式
3. 检查网络连接
4. 查看 API Key 的使用统计

### 问题 3：npx 命令执行缓慢

**解决方案**：

使用全局安装方式：

```bash
npm install -g @gongcishi/remind-mcp-server
```

然后修改配置为：

```json
{
  "mcpServers": {
    "gongcishi-remind": {
      "command": "gongcishi-remind-mcp",
      "env": {
        "GONGCISHI_API_KEY": "your_api_key"
      }
    }
  }
}
```

## 📚 相关链接

- 🏠 [共此时提醒小程序](https://remind.gongcishi.cn)
- 📖 [MCP 官方文档](https://modelcontextprotocol.io)
- 🐛 [问题反馈](https://github.com/gongcishi/remind-mcp-server/issues)
- 💬 [讨论区](https://github.com/gongcishi/remind-mcp-server/discussions)

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

在提交 PR 之前，请确保：

1. 代码通过 TypeScript 编译
2. 遵循现有的代码风格
3. 添加必要的注释和文档

## 🙏 致谢

- [Model Context Protocol](https://modelcontextprotocol.io) - 提供标准协议
- [Anthropic Claude](https://claude.ai) - AI 助手平台
- 所有贡献者和用户

---

Made with ❤️ by Gongcishi Team