Skip to content

Commit 7e0d3d9

Browse files
author
Phatchara Maichandi
committed
Initial commit: macOS Notification MCP server with sound, banner, and speech capabilities.
0 parents  commit 7e0d3d9

7 files changed

Lines changed: 526 additions & 0 deletions

File tree

‎.gitignore‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# Python
2+
__pycache__/
3+
*.py[cod]
4+
*$py.class
5+
*.so
6+
.Python
7+
build/
8+
develop-eggs/
9+
dist/
10+
downloads/
11+
eggs/
12+
.eggs/
13+
lib/
14+
lib64/
15+
parts/
16+
sdist/
17+
var/
18+
wheels/
19+
*.egg-info/
20+
.installed.cfg
21+
*.egg
22+
MANIFEST
23+
*.manifest
24+
*.spec
25+
pip-log.txt
26+
pip-delete-this-directory.txt
27+
htmlcov/
28+
.tox/
29+
.nox/
30+
.coverage
31+
.coverage.*
32+
.cache
33+
nosetests.xml
34+
coverage.xml
35+
*.cover
36+
.hypothesis/
37+
.pytest_cache/
38+
pytest.ini
39+
40+
# Virtual environments
41+
venv/
42+
ENV/
43+
env/
44+
.env
45+
.venv
46+
env.bak/
47+
venv.bak/
48+
49+
# macOS
50+
.DS_Store
51+
.AppleDouble
52+
.LSOverride
53+
Icon
54+
._*
55+
.DocumentRevisions-V100
56+
.fseventsd
57+
.Spotlight-V100
58+
.TemporaryItems
59+
.Trashes
60+
.VolumeIcon.icns
61+
.com.apple.timemachine.donotpresent
62+
.AppleDB
63+
.AppleDesktop
64+
Network Trash Folder
65+
Temporary Items
66+
.apdisk
67+
68+
# Editors
69+
# VSCode
70+
.vscode/*
71+
!.vscode/settings.json
72+
!.vscode/tasks.json
73+
!.vscode/launch.json
74+
!.vscode/extensions.json
75+
*.code-workspace
76+
77+
# JetBrains IDEs
78+
.idea/
79+
*.iml
80+
*.iws
81+
*.ipr
82+
.idea_modules/
83+
out/
84+
85+
# Sublime Text
86+
*.tmlanguage.cache
87+
*.tmPreferences.cache
88+
*.stTheme.cache
89+
*.sublime-workspace
90+
*.sublime-project
91+
92+
# Project specific
93+
*.bak
94+
*.swp
95+
*~
96+
logs/
97+
*.log
98+
.env.local
99+
.env.development.local
100+
.env.test.local
101+
.env.production.local
102+
103+
# Distribution / packaging
104+
.Python
105+
build/
106+
develop-eggs/
107+
dist/
108+
downloads/
109+
eggs/
110+
.eggs/
111+
lib/
112+
lib64/
113+
parts/
114+
sdist/
115+
var/
116+
wheels/
117+
*.egg-info/
118+
.installed.cfg
119+
*.egg
120+
MANIFEST

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 Phatchara Maichandi
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# 🔔 macOS Notification MCP
2+
3+
A Model Context Protocol (MCP) server that enables AI assistants to trigger macOS notifications, sounds, and text-to-speech.
4+
5+
## ✨ Features
6+
7+
- 🔊 **Sound Notifications**: Play system sounds like Submarine, Ping, or Tink
8+
- 💬 **Banner Notifications**: Display visual notifications with customizable title, message, and subtitle
9+
- 🗣️ **Speech Notifications**: Convert text to speech with adjustable voice, rate, and volume
10+
- 🎙️ **Voice Management**: List and select from available system voices
11+
- 🧪 **Testing Tools**: Diagnostic utilities to verify all notification methods
12+
13+
## 🚀 Quick Start with uvx (Recommended)
14+
15+
The fastest way to use this tool is with `uvx`, which runs packages without permanent installation:
16+
17+
```bash
18+
# Install uv if you don't have it
19+
curl -LsSf https://astral.sh/uv/install.sh | sh
20+
21+
# Run the MCP server directly (no installation needed)
22+
uvx macos-notification-mcp
23+
```
24+
25+
## ⚙️ Configure Claude Desktop
26+
27+
Add this to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json`):
28+
29+
```json
30+
{
31+
"mcpServers": {
32+
"macos-notification-mcp": {
33+
"command": "uvx",
34+
"args": ["macos-notification-mcp"]
35+
}
36+
}
37+
}
38+
```
39+
40+
Then restart Claude Desktop.
41+
42+
## 📦 Alternative Installation Methods
43+
44+
Standard installation:
45+
46+
```bash
47+
pip install macos-notification-mcp
48+
```
49+
50+
Install from source:
51+
52+
```bash
53+
git clone https://github.com/devizor/macos-notification-mcp
54+
cd macos-notification-mcp
55+
pip install .
56+
```
57+
58+
## 🛠️ Available Notification Tools
59+
60+
### 🔊 Sound Notification
61+
```python
62+
sound_notification(sound_name="Submarine")
63+
```
64+
Available sounds: Basso, Blow, Bottle, Frog, Funk, Glass, Hero, Morse, Ping, Pop, Purr, Sosumi, Submarine, Tink
65+
66+
### 💬 Banner Notification
67+
```python
68+
banner_notification(
69+
title="Task Complete",
70+
message="Your analysis is ready",
71+
subtitle=None, # Optional
72+
sound=False, # Optional: Play sound with notification
73+
sound_name=None # Optional: Specify system sound
74+
)
75+
```
76+
77+
### 🗣️ Speech Notification
78+
```python
79+
speak_notification(
80+
text="The process has completed",
81+
voice=None, # Optional: System voice to use
82+
rate=150, # Optional: Words per minute (default: 150)
83+
volume=1.0 # Optional: Volume level 0.0-1.0
84+
)
85+
```
86+
87+
### 🎙️ Voice Management
88+
```python
89+
list_available_voices() # Lists all available text-to-speech voices
90+
```
91+
92+
### 🧪 Testing
93+
```python
94+
test_notification_system() # Tests all notification methods
95+
```
96+
97+
## 🔒 Implementation Details
98+
99+
- ⏱️ **Rate Limiting**: Notifications are processed one at a time with a minimum interval of 0.5 seconds
100+
- 🔄 **Queuing**: Multiple notification requests are handled sequentially
101+
- 🪟 **OS Integration**: Uses native macOS commands (`afplay`, `osascript`, `say`)
102+
- 🔌 **FastMCP**: Built on the FastMCP framework for AI communication
103+
104+
## ⚠️ Troubleshooting
105+
106+
- 🔐 **Permissions**: Ensure notifications are allowed in System Settings → Notifications
107+
- ⏳ **Timing**: Only one notification is processed at a time
108+
- 🌐 **Environment**: If using the command directly (not uvx), you may need to use full paths
109+
110+
## 📄 License
111+
112+
MIT License

‎pyproject.toml‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
[build-system]
2+
requires = ["setuptools>=61.0", "wheel"]
3+
build-backend = "setuptools.build_meta"
4+
5+
[project]
6+
name = "macos-notification-mcp"
7+
version = "0.1.1"
8+
description = "macOS Notification MCP Server with sound, banner, and speech alerts"
9+
readme = "README.md"
10+
authors = [{name = "Phatchara Maichandi"}]
11+
license = {text = "MIT"}
12+
classifiers = [
13+
"Programming Language :: Python :: 3",
14+
"License :: OSI Approved :: MIT License",
15+
"Operating System :: MacOS"
16+
]
17+
dependencies = ["fastmcp>=1.0.0"]
18+
requires-python = ">=3.9"
19+
20+
[project.scripts]
21+
macos-notification-mcp = "macos_notification_mcp.server:main"
22+
23+
[tool.setuptools]
24+
package-dir = {"" = "src"}
25+
packages = ["macos_notification_mcp"]

‎setup.py‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
#!/usr/bin/env python3
2+
from setuptools import setup
3+
4+
if __name__ == "__main__":
5+
setup()

‎src/macos_notification_mcp/__init__.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
from .server import mcp
2+
from .server import sound_notification, banner_notification, speak_notification, list_available_voices, test_notification_system

0 commit comments

Comments
 (0)