{"id":28579640,"url":"https://github.com/pinkpixel-dev/notification-mcp","last_synced_at":"2026-04-18T17:03:24.817Z","repository":{"id":296335225,"uuid":"993016024","full_name":"pinkpixel-dev/notification-mcp","owner":"pinkpixel-dev","description":"A Model Context Protocol server that allows AI agents to play a notification sound via a tool when a task is completed.","archived":false,"fork":false,"pushed_at":"2025-05-31T18:36:06.000Z","size":74,"stargazers_count":8,"open_issues_count":2,"forks_count":6,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-30T13:55:09.417Z","etag":null,"topics":["agent","ai","llm","mcp","mcp-server","mcp-tools","model-context-protocol","model-context-protocol-servers","nodejs","notifications","sound","typescript"],"latest_commit_sha":null,"homepage":"https://pinkpixel.dev","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pinkpixel-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-30T04:34:45.000Z","updated_at":"2025-09-07T10:32:03.000Z","dependencies_parsed_at":"2025-05-30T05:53:13.509Z","dependency_job_id":"2c47a954-163b-411c-8ed2-31f20695533f","html_url":"https://github.com/pinkpixel-dev/notification-mcp","commit_stats":null,"previous_names":["pinkpixel-dev/notification-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pinkpixel-dev/notification-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinkpixel-dev%2Fnotification-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinkpixel-dev%2Fnotification-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinkpixel-dev%2Fnotification-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinkpixel-dev%2Fnotification-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pinkpixel-dev","download_url":"https://codeload.github.com/pinkpixel-dev/notification-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinkpixel-dev%2Fnotification-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31976806,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T16:27:12.723Z","status":"ssl_error","status_checked_at":"2026-04-18T16:27:11.140Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai","llm","mcp","mcp-server","mcp-tools","model-context-protocol","model-context-protocol-servers","nodejs","notifications","sound","typescript"],"created_at":"2025-06-11T02:09:10.479Z","updated_at":"2026-04-18T17:03:24.773Z","avatar_url":"https://github.com/pinkpixel-dev.png","language":"JavaScript","funding_links":[],"categories":["🤖 AI/ML","Other Tools and Integrations"],"sub_categories":["How to Submit"],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://res.cloudinary.com/di7ctlowx/image/upload/v1748659972/notification-mcp-logo_ymwx1p.jpg\" alt=\"Notification MCP Logo\" width=\"200\" height=\"200\"/\u003e\n\n  # ✨ Notifications MCP Server ✨\n\n  **Dream it, Pixel it. Made with ❤️ by Pink Pixel.**\n\n  [![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![Model Context Protocol](https://img.shields.io/badge/Model%20Context%20Protocol-Server-green)](https://github.com/model-context-protocol/model-context-protocol) [![npm version](https://badge.fury.io/js/@pinkpixel%2Fnotification-mcp.svg)](https://www.npmjs.com/package/@pinkpixel/notification-mcp) [![smithery badge](https://smithery.ai/badge/@pinkpixel-dev/notification-mcp)](https://smithery.ai/server/@pinkpixel-dev/notification-mcp)\n\n  [![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge\u0026logo=typescript\u0026logoColor=white)](https://www.typescriptlang.org/) [![Node.js](https://img.shields.io/badge/Node.js-43853D?style=for-the-badge\u0026logo=node.js\u0026logoColor=white)](https://nodejs.org/) [![npm](https://img.shields.io/badge/npm-CB3837?style=for-the-badge\u0026logo=npm\u0026logoColor=white)](https://www.npmjs.com/package/@pinkpixel/notification-mcp)\n\n  [![NPM Downloads](https://img.shields.io/npm/dm/@pinkpixel/notification-mcp?style=flat-square\u0026color=ff69b4)](https://www.npmjs.com/package/@pinkpixel/notification-mcp) [![GitHub Stars](https://img.shields.io/github/stars/pinkpixel-dev/notification-mcp?style=flat-square\u0026color=ff69b4)](https://github.com/pinkpixel-dev/notification-mcp/stargazers) [![GitHub Issues](https://img.shields.io/github/issues/pinkpixel-dev/notification-mcp?style=flat-square\u0026color=ff69b4)](https://github.com/pinkpixel-dev/notification-mcp/issues) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-ff69b4.svg?style=flat-square)](http://makeapullrequest.com)\n\n  [![Platform Support](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS-lightgrey?style=flat-square)](https://github.com/pinkpixel-dev/notification-mcp) [![Built with Love](https://img.shields.io/badge/Built%20with-❤️-ff1744.svg?style=flat-square)](https://pinkpixel.dev) [![Pink Pixel](https://img.shields.io/badge/Pink-Pixel-ff69b4?style=flat-square\u0026logo=sparkles)](https://pinkpixel.dev)\n\n\u003c/div\u003e\n\n## Overview\n\nA Model Context Protocol server that allows AI agents to play notification sounds when tasks are completed. This TypeScript-based MCP server provides a simple, configurable notification system with **bundled sounds that work out of the box** with npx!\n\n## ✨ Features\n\n### 🔧 Tools\n- `play_notification` - Play a notification sound to indicate task completion\n  - Takes an optional `message` parameter to display with the notification\n  - Supports cross-platform sound playback (Windows and macOS)\n  - **Works with bundled sounds** - no manual downloads required!\n\n### 🎵 Built-in Sound Library\n**5 high-quality notification sounds bundled with the package:**\n- `cosmic` - Space-themed notification 🌌\n- `fairy` - Magical, whimsical tone 🧚‍♀️\n- `gentle` - Soft, pleasant default sound (default) 🔔\n- `pleasant` - Balanced, professional tone 📞\n- `retro` - Nostalgic, vintage-style notification 🕹️\n- `random` - Randomly plays one of the 5 sounds 🎲\n\n## 🚀 Quick Start\n\n### Option 1: Use Bundled Sounds (Recommended) ⭐\nJust run it with npx - sounds included!\n\n```json\n{\n  \"mcpServers\": {\n    \"notifications\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@pinkpixel/notification-mcp\"]\n    }\n  }\n}\n```\n\n### Option 2: Choose a Different Bundled Sound\n```json\n{\n  \"mcpServers\": {\n    \"notifications\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@pinkpixel/notification-mcp\"],\n      \"env\": {\n        \"MCP_NOTIFICATION_SOUND\": \"cosmic\"\n      }\n    }\n  }\n}\n```\n\n### Option 3: Random Sound Each Time 🎲\n```json\n{\n  \"mcpServers\": {\n    \"notifications\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@pinkpixel/notification-mcp\"],\n      \"env\": {\n        \"MCP_NOTIFICATION_SOUND\": \"random\"\n      }\n    }\n  }\n}\n```\n\n### Option 4: Use Your Own Custom Sound\n```json\n{\n  \"mcpServers\": {\n    \"notifications\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@pinkpixel/notification-mcp\"],\n      \"env\": {\n        \"MCP_NOTIFICATION_SOUND_PATH\": \"C:\\\\path\\\\to\\\\your\\\\sound.mp3\"\n      }\n    }\n  }\n}\n```\n\n## ⚙️ Configuration\n\nThe notification sound can be configured using environment variables:\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `MCP_NOTIFICATION_SOUND` | Choose from bundled sounds: `cosmic`, `fairy`, `gentle`, `pleasant`, `retro`, `random` | `gentle` |\n| `MCP_NOTIFICATION_SOUND_PATH` | Absolute path to your own MP3 file (overrides bundled sounds) | `null` |\n\n### Priority Order\n1. **Custom Path** (`MCP_NOTIFICATION_SOUND_PATH`) - highest priority\n2. **Bundled Sound** (`MCP_NOTIFICATION_SOUND`) - choose from 5 included sounds\n3. **Default** - gentle chime if nothing is specified\n\n## 💻 Usage\n\nOnce configured, your MCP client can call the `play_notification` tool:\n\n```typescript\nawait client.request({\n  method: \"tools/call\",\n  params: {\n    name: \"play_notification\",\n    arguments: {\n      message: \"Task completed successfully! 🎉\"\n    }\n  }\n});\n```\n\n## 🛠️ Development\n\n### Local Development Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/pinkpixel-dev/notification-mcp.git\ncd notification-mcp\n\n# Install dependencies\nnpm install\n\n# Build the server\nnpm run build\n\n# For development with auto-rebuild\nnpm run watch\n```\n\n### Local Development Configuration\n```json\n{\n  \"mcpServers\": {\n    \"notifications\": {\n      \"command\": \"node\",\n      \"args\": [\"./build/index.js\"],\n      \"env\": {\n        \"MCP_NOTIFICATION_SOUND\": \"retro\"\n      }\n    }\n  }\n}\n```\n\n### Debugging\n\nUse the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) for interactive debugging:\n\n```bash\nnpm run inspector\n```\n\nThe Inspector provides a web interface to test your MCP server in your browser.\n\n## 📦 Installation Methods\n\n### NPX (Recommended)\nNo installation required - sounds are bundled automatically:\n```bash\nnpx @pinkpixel/notification-mcp\n```\n\n### Global Install\n```bash\nnpm install -g @pinkpixel/notification-mcp\nnotification-mcp\n```\n\n### Local Install\n```bash\nnpm install @pinkpixel/notification-mcp\nnpx notification-mcp\n```\n\n## 🎵 Sound Files\n\nAll sound files are located in the `sounds/` directory and are automatically included when you install the package:\n\n- Cosmic: `sounds/cosmic_chime.mp3` - 🌌 Space-themed\n- Fairy: `sounds/fairy_chime.mp3` - 🧚‍♀️ Magical\n- Gentle: `sounds/gentle_chime.mp3` - 🔔 Default (soft)\n- Pleasant:`sounds/pleasant_chime.mp3` - 📞 Professional\n- Retro: `sounds/retro_chime.mp3` - 🕹️ Vintage\n- Random: Set `MCP_NOTIFICATION_SOUND=random` - 🎲 Surprise me!\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🌟 About Pink Pixel\n\n- **Website:** [pinkpixel.dev](https://pinkpixel.dev)\n- **GitHub:** [github.com/pinkpixel-dev](https://github.com/pinkpixel-dev)\n- **Discord:** @sizzlebop\n\n---\n\n*Made with ❤️ by Pink Pixel* ✨\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpinkpixel-dev%2Fnotification-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpinkpixel-dev%2Fnotification-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpinkpixel-dev%2Fnotification-mcp/lists"}