mcp-notify

AI 에이전트가 작업을 완료하거나 주의가 필요할 때 컴퓨터에서 알림 사운드를 재생하고 시스템 배너를 표시하는 초경량(超輕量) MCP 서버입니다.

Claude Desktop, Claude Code, Cursor, VS Code, opencode, Cline 등 모든 MCP 클라이언트에서 작동합니다. 3줄이면 끝나는 설정, API 키 불필요, 네트워크 호출 없음 — 로컬 오디오 및 알림 기능만 건드립니다.

설치

클라이언트의 MCP 설정(Claude Desktop은 claude_desktop_config.json, Cursor / VS Code는 mcp.json, 그 외 opencode 설정)에 추가하세요:

{
  "mcpServers": {
    "mcp-notify": {
      "command": "npx",
      "args": ["-y", "@mrfqcentic/mcp-notify"]
    }
  }
}

(opencode 사용자: mcp 키 아래에 "type": "local"을 두고, "command": ["npx", "-y", "@mrfqnotify/mcp-notify"]를 사용하는 동일한 형태입니다.)

Node.js >= 20이 필요합니다.

Related MCP server: Notifications MCP Server

에이전트가 이 기능을 호출하도록 설정

AGENTS.md / CLAUDE.md / 시스템 프롬프트에 한 줄을 추가하세요:

When a task is done or the user should be alerted, call the `notify` tool with a short title and a 1–2 sentence description of the result.

Tools

notify

사운드를 재생하고 배너를 표시합니다. 에이전트는 항상 title(최대 50자)과 message(최대 200자)를 제공해야 합니다.

list_sounds

사용 가능한 사운드와 현재 선택된 기본 사운드를 나열합니다.

사운드 선택

우선 적용 순서:

1. NOTIFY_SOUND 환경 변수 — 절대 경로, 명시적이고 결정론적

2. sounds/ 폴더에서 이름이 default로 시작하는 파일 (내가 고정한 사운드)

3. sounds/ 폴더의 첫 번째 오디오 파일 (알파벳순 — 번들 기본 사운드인 notify-me.mp3가 여기 포함됨)

4. assets/에 생성된 차임

5. 시스템 사운드 (macOS Glass.aiff, Linux bell.oga)

팁: 마음에 드는 사운드를 sounds/default.mp3로 이름을 바꾸거나 복사하세요 (또는 NOTIFY_SOUND를 설정). 이후에도 유지됩니다.

번들로 제공되는 sounds/notify-me.mp3는 상업 라이선스에 따라 ElevenLabs로 생성되었습니다.

{
  "mcpServers": {
    "mcp-notify": {
      "command": "npx",
      "args": ["-y", "@mrfqcentic/mcp-notify"],
      "env": { "NOTIFY_SOUND": "/absolute/path/to/your-sound.mp3" }
    }
  }
}

팁: 오디오 트랙이 있는 MP4 파일도 작동합니다 (macOS afplay는 오디오 스트림을 읽습니다).

플랫폼

CI 환경 변수에 값이 있으면 사운드 및 배너 재생은 no-op가 됩니다 (CI 워크플로에서 자동 설정됨). 그래서 오디오가 없는 머신에서도 테스트 스위트를 실행할 수 있습니다.

개발

npm install
npm run typecheck
npm test          # builds, then runs the e2e suite (sound + banner fire locally)

라이선스

MIT — LICENSE 참조.