通知-mcp服务器

Name: 通知-mcp服务器
Author: charles-adedotun

作者：charles-adedotun11 星标更新：2025-07-26

安装使用来源：spider==github.com

项目介绍

Claude 通知服务器

一个轻量级的MCP服务器，为macOS上的Claude桌面提供听觉和视觉通知。该服务器会在Claude开始处理您的请求以及完成任务时通知您。

功能

🔔 在Claude响应的开始和结束时发出不同的声音通知
💻 兼容macOS原生系统声音（.aiff文件）
🎵 通过环境变量轻松自定义通知声音
🔔 通过macOS通知中心进行视觉桌面通知
🖼️ 自定义视觉通知图标
🚀 简单设置，依赖项最少
📱 多种通知方法及备选方案（PyObjC, pync, AppleScript, terminal-notifier）

安装与设置

预备条件

macOS（通知依赖于macOS特定的功能）
Python 3.8或更高版本
Claude桌面应用程序

快速安装

克隆仓库：

git clone https://github.com/charles-adedotun/notifications-mcp-server.git
cd notifications-mcp-server

安装uv（如果尚未安装）：

# 选项1：使用curl
curl -LsSf https://astral.sh/uv/install.sh | sh

# 选项2：使用Homebrew
brew install uv

安装包及其依赖项：

# 开发模式下安装包
uv pip install -e .

# 或直接从仓库安装
uv pip install git+https://github.com/charles-adedotun/notifications-mcp-server.git

# 安装视觉通知依赖项（推荐）
uv pip install pyobjc-core pyobjc-framework-Cocoa

测试安装：

# 运行测试脚本以验证通知是否正常工作
uv run python test_notification.py

# 直接运行通知服务器
uv run claude-notifications

配置Claude桌面：

编辑Claude的配置以包含通知服务器：
```
{
  "mcpServers": {
    "notify-user": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "fastmcp",
        "run",
        "/path/to/server.py"
      ]
    }
  }
}
```
将/path/to/server.py替换为您系统上server.py文件的实际绝对路径。

如果mcpServers对象已经存在，请仅添加新的服务器配置到其中。
重启Claude桌面
测试通知：
```
uv run python test_notification.py
```
这将测试所有可用的通知方法，并帮助诊断任何问题。

工作原理

安装后，服务器会自动连接到Claude桌面并提供task_status通知工具。Claude将在每次交互的开始和结束时调用此工具，产生听觉和视觉通知。

架构

┌─────────────────┐     MCP协议      ┌─────────────────┐     系统命令    ┌─────────────┐
│                 │ ──────────────────>   │                 │ ──────────────────>   │ macOS 声音 │
│  Claude 桌面   │                       │   通知         │                       │    系统   │
│   应用程序     │ <──────────────────   │   MCP 服务器   │ <──────────────────   │             │
│                 │                       │                 │                       └─────────────┘
                                          │                 │                       ┌───────────-──┐
                                          │                 │ ──────────────────>   │ macOS        │
                                          │                 │                       │ 通知中心     │
                                          │                 │ <──────────────────   │              │
                                          └─────────────────┘                       └─────────────-┘

通知服务器使用多种方法来传递视觉通知，并具有自动回退机制：

PyObjC（原生macOS通知） - 首先尝试
pync（如果已安装） - 如果PyObjC失败则尝试
AppleScript（始终有效） - 作为回退
terminal-notifier（如果已安装） - 最后选择

这确保至少有一种通知方法在您的系统上可以工作。

项目结构

Claude通知MCP服务器现在组织成模块化结构：

notifications/
├── __init__.py             # 包初始化，带有版本信息
├── core/                   # 核心功能
│   ├── __init__.py
│   ├── sound_manager.py    # 声音播放管理
│   └── notification_manager.py  # 视觉通知管理
├── platform/               # 平台特定实现
│   ├── __init__.py
│   └── macos/              # macOS特定代码
│       ├── __init__.py
│       ├── sound.py        # macOS声音函数
│       └── notification.py # macOS通知方法
├── utils/                  # 实用函数
│   ├── __init__.py
│   ├── config.py           # 配置常量和辅助函数
│   └── logging.py          # 日志设置
└── server.py               # MCP服务器实现

这种模块化结构提高了可维护性，并且在未来更容易添加对其他平台的支持。

LLM的MCP配置

要配置LLM使用此通知服务器，请在您的MCP配置中添加以下内容：

{
  "notify-user": {
    "command": "uv",
    "args": [
      "run",
      "--with",
      "fastmcp",
      "fastmcp",
      "run",
      "/path/to/server.py"
    ]
  }
}

将/path/to/server.py替换为您系统上server.py文件的实际绝对路径。

此配置使用uv命令来运行通知服务器及其所需依赖项。

自定义通知

声音通知

默认声音

任务开始："Glass.aiff"来自macOS系统声音
任务结束："Hero.aiff"来自macOS系统声音

自定义声音

# 对于开始通知
export CLAUDE_START_SOUND="/System/Library/Sounds/Ping.aiff"

# 对于完成通知
export CLAUDE_COMPLETE_SOUND="/System/Library/Sounds/Purr.aiff"

# 设置环境变量后，重新启动通知服务器

视觉通知

# 禁用视觉通知
export CLAUDE_VISUAL_NOTIFICATIONS="false"

# 设置自定义通知图标
export CLAUDE_NOTIFICATION_ICON="/path/to/your/custom/icon.png"

# 设置环境变量后，重新启动通知服务器

使设置永久生效

添加到您的shell配置文件（~/.zshrc, ~/.bashrc或类似文件）：

# 对于不同声音
echo 'export CLAUDE_START_SOUND="/System/Library/Sounds/Ping.aiff"' >> ~/.zshrc
echo 'export CLAUDE_COMPLETE_SOUND="/System/Library/Sounds/Purr.aiff"' >> ~/.zshrc

# 对于视觉通知
echo 'export CLAUDE_VISUAL_NOTIFICATIONS="true"' >> ~/.zshrc
echo 'export CLAUDE_NOTIFICATION_ICON="/path/to/your/icon.png"' >> ~/.zshrc

source ~/.zshrc

可用的系统声音

macOS提供了这些内置声音在/System/Library/Sounds/：

声音名称	描述
Basso.aiff	深沉、严肃的音调
Blow.aiff	类似风的声音
Bottle.aiff	瓶子爆裂声
Frog.aiff	青蛙叫声
Funk.aiff	狂野电子音
Glass.aiff	玻璃敲击声（默认）
Hero.aiff	胜利之声
Morse.aiff	短的摩尔斯电码哔声
Ping.aiff	经典的ping通知
Pop.aiff	短的爆裂声
Purr.aiff	温柔的咕噜声
Sosumi.aiff	苹果的经典警报
Submarine.aiff	潜艇ping
Tink.aiff	轻微的叮当声

您可以预览这些声音：

afplay /System/Library/Sounds/Glass.aiff

您也可以使用自己的.aiff文件，只需提供完整路径即可。

故障排除

视觉通知未工作

运行测试脚本：
```
uv run python test_notification.py
```
这个全面测试将尝试所有通知方法并提供诊断信息。
检查通知权限：
- 前往系统偏好设置 → 通知
- 查找可能处理通知的应用程序：
  - Python
  - 终端
  - osascript (AppleScript)
- 确保这些应用程序的通知已启用
您可以直接打开通知偏好设置：
```
open "x-apple.systempreferences:com.apple.preference.notifications"
```
尝试安装terminal-notifier：
```
brew install terminal-notifier
```
这提供了额外的通知回退方法。
检查服务器日志：
- 查看终端中的错误消息，服务器正在运行的地方
- 在Claude桌面中，启用开发者模式（帮助菜单 → 启用开发者模式）
- 在开发者菜单中检查MCP日志文件

声音通知未工作

验证您的macOS声音设置：
- 确保系统音量未静音
- 尝试直接播放声音：afplay /System/Library/Sounds/Glass.aiff
检查自定义声音路径：
- 如果指定了自定义声音，请确保路径正确
- 使用.aiff文件以获得最佳兼容性

服务器未连接

验证Claude桌面配置：
- 检查claude_desktop_config.json中server.py文件的路径是否正确
- 确保服务器已在您的Claude桌面设置中正确配置
重启所有服务：
- 重启Claude桌面
- 如有必要，重启计算机
检查依赖项：
- 确保所有必需的包均已安装：uv pip list | grep fastmcp
- 尝试重新安装：uv pip install -e .
检查服务器日志：
- 查看终端中的错误消息，服务器正在运行的地方
- 在Claude桌面中，启用开发者模式（帮助菜单 → 启用开发者模式）
- 在开发者菜单中检查MCP日志文件

卸载

删除仓库：

rm -rf /path/to/notifications-mcp-server

如果您安装了Python包：

# 删除使用uv安装的包
uv pip uninstall notifications-mcp-server fastmcp pyobjc-core pyobjc-framework-Cocoa pync

开发

需求： Python 3.10+，fastmcp库，通知库

使用uv运行测试：

uv pip install pytest pytest-cov
pytest

许可证

本项目根据MIT许可证授权。

致谢

使用Anthropic的FastMCP库构建
特别感谢所有贡献者和Claude社区