Claude Notifier

🎯 Windows 桌面通知工具 - 简单优雅的通知体验

一个简洁美观的 Windows 桌面通知工具，支持命令行快速发送通知，完美集成到 Claude Code。

✨ 特性

• 🎨 美观设计 - 现代化 UI，深色/浅色主题
• 📍 灵活定位 - 6 个屏幕位置可选
• 🔔 未读计数 - 智能统计未读通知
• 🔒 并发安全 - 多通知同时发送自动排队
• ⏱️ 自动隐藏 - 超时自动消失，不干扰工作
• 🪟 窗口激活 - 点击"查看"回到原窗口
• 🔗 MCP 协议 - 与 Claude Code 无缝集成
• ⚡ 高效执行 - 使用 -EncodedCommand 避免 PowerShell 临时文件
• 🧹 自动清理 - MCP 服务器启动时自动清理旧实例

🚀 快速开始

方式 1：Claude Code 集成（推荐）

1.1 安装

无需手动安装，在 Claude Code 的配置文件中添加以下配置即可自动安装：

配置文件位置：

• Windows: C:\Users\{用户名}\AppData\Roaming\Code\User\settings.json
• 或者: C:\Users\{用户名}\.claude.json

1.2 配置 MCP 服务器

在配置文件中添加 mcpServers 配置：

{
  "mcpServers": {
    "claude-notifier": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "@linjian612/claude-notifier-mcp@latest"],
      "env": {
        "NOTIFIER_TITLE": "Claude Code 通知",
        "NOTIFIER_THEME": "light",
        "NOTIFIER_POSITION": "bottom-right",
        "NOTIFIER_TIMEOUT": "15000"
      }
    }
  }
}

1.3 配置 Hooks（可选）

添加 Hooks 配置以实现窗口激活功能：

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "npx --package=@linjian612/claude-notifier-mcp@latest -y claude-notifier-cli --on-session-start"
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "npx --package=@linjian612/claude-notifier-mcp@latest -y claude-notifier-cli --on-notification"
          }
        ]
      }
    ]
  }
}

参数说明：

• --package=@linjian612/claude-notifier-mcp@latest - 指定 npm 包名（不是命令名）
• -y - 自动确认安装，避免交互式提示

1.4 在 Claude 中使用

配置完成后，重启 Claude Code，然后就可以在对话中使用：

发送通知：notifier_send(message="任务完成！")
带状态：notifier_send(message="代码编译完成", subTitle="已完成")

方式 2：本地项目使用

# 克隆项目
git clone <repository-url>
cd claude-notifier-mcp

# 安装依赖
npm install

# 构建
npm run build

# 发送通知
npm run notify -- --message="任务完成！"

方式 3：直接使用 CLI

⚠️ 重要提示：必须使用 --package 参数指定包名，否则会报 404 错误。

# 基本用法（推荐格式）
npx --package=@linjian612/claude-notifier-mcp@latest -y claude-notifier-cli --message="消息内容"

# 带副标题
npx --package=@linjian612/claude-notifier-mcp@latest -y claude-notifier-cli --message="构建成功" --sub-title="已完成"

# 查看版本号
npx --package=@linjian612/claude-notifier-mcp@latest -y claude-notifier-cli --version

命令格式说明：

• --package=@linjian612/claude-notifier-mcp@latest - 指定包名和版本（必需）
• -y - 自动确认安装，避免交互式提示
• claude-notifier-cli - 实际执行的命令名

为什么不能用 npx claude-notifier-cli？

• npx 查找的是包名（package name），不是命令名（bin command）
• 本项目的包名是 @linjian612/claude-notifier-mcp，命令名是 claude-notifier-cli
• 必须用 --package 参数明确指定包名

全局安装后可简化命令：

# 先全局安装
npm install -g @linjian612/claude-notifier-mcp

# 之后可以直接使用命令名
claude-notifier-cli --message="消息"

📖 使用示例

npm 脚本使用

# 简单消息
npm run notify -- --message="任务完成！"

# 带副标题
npm run notify -- --message="构建成功" --sub-title="已完成"

# 自定义标题
npm run notify -- --message="部署完成" --title="CI/CD"

# 深色主题
npm run notify -- --message="重要通知" --theme="dark"

# 自定义位置
npm run notify -- --message="通知" --position="top-right"

# 自定义时长
npm run notify -- --message="提醒" --timeout="30000"

管道输入

# 从其他命令输出
echo "编译完成" | npm run notify

# 构建脚本示例
npm run build && npm run notify -- --message="构建完成！"

# Git 提交后通知
git commit && npm run notify -- --message="代码已提交" --sub-title="成功"

环境变量配置

Windows PowerShell:

$env:NOTIFIER_TITLE="我的应用"
$env:NOTIFIER_THEME="dark"
$env:NOTIFIER_POSITION="top-right"
$env:NOTIFIER_TIMEOUT="10000"
npm run notify -- --message="消息"

Windows CMD:

set NOTIFIER_TITLE=我的应用&& set NOTIFIER_THEME=dark&& npm run notify -- --message="消息"

实际应用场景

脚本完成通知

#!/bin/bash
# 执行构建
npm run build

# 发送通知
npm run notify -- \
  --message="项目构建成功" \
  --sub-title="已完成" \
  --theme="light"

定时提醒

# 15分钟后提醒
sleep 900 && npm run notify -- \
  --message="会议即将开始" \
  --sub-title="15分钟后" \
  --timeout="30000"

长时间任务通知

# 数据备份完成后通知
backup_script.sh && npm run notify -- \
  --message="数据备份完成" \
  --sub-title="成功" \
  --theme="dark"

📋 参数说明

命令行参数

| 参数 | 说明 | 默认值 | 示例 | | ------------ | ---------------- | ---------------- | ------------------------ | | --message | 通知内容（必填） | - | --message="消息" | | --subTitle | 副标题/状态 | 空 | --subTitle="已完成" | | --title | 通知标题 | Claude Code 通知 | --title="我的应用" | | --theme | 主题 | light | --theme="dark" | | --position | 位置 | bottom-right | --position="top-right" | | --timeout | 显示时长(毫秒) | 15000 | --timeout="30000" | | --stop | 停止所有实例 | - | --stop | | --restart | 清理并重启 | - | --restart | | --version | 显示版本号 | - | --version |

环境变量

| 变量 | 说明 | 默认值 | | ------------------- | ---------- | ---------------- | | NOTIFIER_TITLE | 通知标题 | Claude Code 通知 | | NOTIFIER_THEME | 主题 | light | | NOTIFIER_POSITION | 位置 | bottom-right | | NOTIFIER_TIMEOUT | 时长(毫秒) | 15000 | | NOTIFIER_DEBUG | 调试模式 | 关闭 |

位置选项

top-left      top-center      top-right
   ❍            ❍              ❍

bottom-left   bottom-center   bottom-right
   ❍            ❍              ❍

🛠️ 开发

开发命令

# 开发模式运行
npm run dev

# 完整构建
npm run build

# 仅构建 MCP 服务器
npm run build:mcp

# 仅构建 Neutralino 应用
npm run build:neutralino

# 停止后台应用
npm run stop

项目结构

├── dist/                   # Neutralino 构建输出
├── dist-mcp/              # MCP 服务器构建输出
│   ├── index.js           # MCP 服务器入口
│   ├── notification-sender.js
│   └── core/              # 核心共享模块（编译后）
├── resources/             # Neutralino 前端资源
├── src/                   # TypeScript 源码
│   ├── index.ts           # MCP 服务器入口
│   ├── notification-sender.ts
│   ├── core/              # 核心共享模块
│   └── types.ts
├── scripts/               # 构建脚本
│   ├── build-neutralino.cjs  # Neutralino 构建脚本
│   └── patch-exe.cjs     # EXE 元数据补丁
├── utils/                 # 通用工具
│   ├── powershell.cjs    # PowerShell 工具（-EncodedCommand）
│   └── window-hwnd.cjs   # 窗口句柄获取
├── cli.cjs                # CLI 入口
├── notify.cjs             # 通知脚本
├── launcher.cjs           # 底层命令行入口（使用核心模块）
└── neutralino.config.json # Neutralino 配置

❓ 常见问题

Q: 点击"查看"按钮有什么用？

A: 点击"查看"会激活发送通知的原始窗口，方便你回到工作状态。需要配置 Hooks 才能使用此功能。

Q: 未读计数是怎么工作的？

A: 同一个窗口连续发送通知时，会累积显示未读数量（如"3条"）。手动关闭或超时后会清零。

Q: 如何停止后台应用？

A: 使用以下任一命令：

# 方式 1: 使用 npm script
npm run stop

# 方式 2: 使用 CLI
npx --package=@linjian612/claude-notifier-mcp@latest -y claude-notifier-cli --stop

# 方式 3: 直接调用 launcher
node launcher.cjs --stop

# 方式 4: 使用 Windows 命令
taskkill /F /IM claude-notifier-win_x64.exe

Q: 更新版本时出现 npm cleanup 警告怎么办？

A: 这是正常的！npx 在尝试清理旧缓存时，如果 exe 正在运行，会显示 cleanup failed 警告。

但这不影响新版本的使用：

1. 新版本已经成功安装
2. MCP 服务器启动时会自动停止旧实例
3. 下次运行时警告会消失

如果需要手动清理，先运行：

npx --package=@linjian612/claude-notifier-mcp@latest -y claude-notifier-cli --stop

Q: 通知不显示怎么办？

A: 检查以下几点：

1. 确认已运行 npm run build
2. 检查 Windows 防火墙设置
3. 查看是否有错误日志
4. 尝试重启：npm run stop && npm run notify -- --message="测试"

Q: 支持 Linux/macOS 吗？

A: 目前仅支持 Windows。Linux/macOS 支持计划在未来的版本中实现。

Q: 如何自定义通知样式？

A: 可以修改 resources/index.html 中的 CSS 样式，然后重新构建：

npm run build:neutralino

Q: 为什么 npx claude-notifier-cli 会报 404 错误？

A: npx 查找的是包名（package name），不是命令名（bin command）。

• 包名：@linjian612/claude-notifier-mcp（在 package.json 中定义）
• 命令名：claude-notifier-cli（在 bin 字段中定义）

正确的命令格式：

npx --package=@linjian612/claude-notifier-mcp@latest -y claude-notifier-cli --message="消息"

或者先全局安装：

npm install -g @linjian612/claude-notifier-mcp
claude-notifier-cli --message="消息"

Q: 在项目目录下可以用简化命令，其他目录不行？

A: 在项目目录下，npx 会优先使用本地的 node_modules/.bin，所以能直接找到 claude-notifier-cli 命令。在其他目录下，必须从远程下载包，需要指定完整的包名。

Q: 发布新版本后，如何确保使用最新版本？

A: 使用 @latest 标签，并在命令前加 -y 参数：

npx --package=@linjian612/claude-notifier-mcp@latest -y claude-notifier-cli --version

或者清除 npm 缓存：

npm cache clean --force

📄 许可证

ISC

👨‍💻 作者

Jerry Lin

享受简洁的通知体验！ ❤️