Content
```markdown
# Notification MCP
> Let AI assistants directly read notifications from your Android phone — Based on [MCP Protocol](https://modelcontextprotocol.io/).
[](LICENSE)
[](https://developer.android.com/about/versions/11)
[](https://kotlinlang.org)
[](https://modelcontextprotocol.io)
## What is this?
Notification MCP runs a local MCP server on your Android phone, allowing AI assistants on your computer (such as MiClaw, Claude Desktop, and any other MCP protocol-supported clients) to query notifications directly using natural language.
**No need to manually check your phone for verification codes, packages, or transfer records** — Just ask your AI assistant.
```
You: Do I have any notifications on my phone?
AI: [Automatically call search_notifications(keyword="verification code")]
AI: Found 2 verification code notifications:
1. China Industrial and Commercial Bank - Verification code 837214, valid for 5 minutes
2. WeChat - Verification code 591638 for login verification
```
## Features
| Feature | Description |
|------|------|
| 🔍 **Smart Search** | Search notifications by keyword, package name, and time range with millisecond-level response |
| 🛡️ **Privacy Desensitization** | Automatically desensitize sensitive information such as phone numbers, IDs, bank cards, and verification codes |
| 🎯 **Five-dimensional Filtering** | Package name blacklist/whitelist + keyword regular expression + priority + notification classification |
| 🔧 **One-click Diagnosis** | Six diagnostic links, 22 automatic checks, and one-click repair of MIUI/HyperOS issues |
| 🔄 **High Availability** | Triple keep-alive + crash self-healing + disconnection compensation, 7×24 hours uninterrupted |
| 📊 **Operation Statistics** | Real-time viewing of notification reception, forwarding, filtering, and abnormal data |
## Installation and Configuration
### Step 1: Download and Install
Download the latest `app-debug.apk` from the [Releases](../../releases) page and install it on your phone.
> ⚠️ During installation, the system may prompt "Unknown source", which is normal (since it's not downloaded from the app store). Click "Install anyway" to continue.
### Step 2: Enable Notification Access
1. Open the Notification MCP app
2. Click the **"Enable Notification Access"** button on the homepage
3. Find **"Notification Access"** (or Notification MCP) in the system settings
4. Enable the switch and confirm authorization
> This permission is required; without it, the app cannot read notification content.
### Step 3: Disable Battery Optimization (Important!)
Android systems will kill high-power consumption apps in the background; you must add Notification MCP to the whitelist:
**Xiaomi/Redmi (MIUI / HyperOS):**
1. Settings → Battery → Intelligent power saving
2. Find "Notification Access" → Select **"No restrictions"**
3. Settings → App settings → App management → Notification Access → Power saving strategy → **"No restrictions"**
4. Settings → App settings → App management → Notification Access → Autostart → **Enable**
**Huawei/Honor (HarmonyOS):**
1. Settings → Battery → Startup management
2. Find "Notification Access" → Disable automatic management → Manual setting: Allow autostart, allow association startup, and allow background activity
**OPPO/realme (ColorOS):**
1. Settings → Battery → More battery settings
2. Enable **"Allow apps to run in the background"**
3. Settings → App management → Notification Access → Power saving strategy → Allow background running
**vivo/iQOO (OriginOS):**
1. Settings → Battery → Background power consumption management
2. Find "Notification Access" → Allow background high power consumption
**Native Android / Samsung (One UI):**
1. Settings → Battery → Battery optimization
2. Find "Notification Access" → Select **"Don't optimize"**
### Step 4: Connect AI Client
The app will run a local MCP server (port 8765) on your phone after startup. Add the following MCP configuration to your AI client:
```json
{
"mcpServers": {
"notification": {
"type": "http",
"url": "http://127.0.0.1:8765/mcp"
}
}
}
```
**Different client configuration methods:**
| Client | Configuration Location |
|--------|----------|
| **MiClaw (Xiaomi AI Assistant)** | Say "Configure local MCP server, address is http://127.0.0.1:8765/mcp, name is Notification Access" to the phone |
| **Claude Desktop** | Settings → MCP Servers → Edit Config → Paste the above JSON |
| **Cursor** | Settings → MCP → Add new global MCP server → Paste the above JSON |
| **Other MCP Clients** | Find the MCP server configuration entry, add HTTP type, and fill in the address `http://127.0.0.1:8765/mcp` |
> 💡 **Note**: The phone and computer must be on the same local network, or the AI client runs directly on the phone. `127.0.0.1` represents the local machine; if the AI client is on the computer, replace `127.0.0.1` with the phone's local network IP (e.g., `192.168.1.100`).
### Step 5: Verify Connection
Input in the AI client:
```
Help me check the recent notifications on my phone
```
If the AI returns the notification list, the configuration is successful 🎉
## MCP Tool List
After a successful connection, AI can call the following tools:
| Tool | Parameters | Description |
|------|------|------|
| `search_notifications` | `keyword`, `hours`(default 24), `limit`(default 20) | Search notifications by keyword |
| `get_notifications` | `limit`(default 50), `package_name` | Get notification list |
| `get_notification_stats` | None | Today's statistics (received/forwarded/filtered/abnormal) |
| `get_filter_rules` | None | View filtering rules |
| `add_filter_rule` | `package_name`, `action`, `reason` | Add filtering rule |
| `delete_filter_rule` | `rule_id` | Delete filtering rule |
| `get_masking_rules` | None | View desensitization rules |
| `add_masking_rule` | `pattern`, `replacement` | Add desensitization rule |
| `run_diagnostic` | None | One-click fault diagnosis |
| `auto_fix` | None | One-click automatic repair |
| `get_diagnostic_history` | None | View diagnosis history |
| `get_logs` | `limit` | Get running logs |
## Project Architecture
```
com.miclaw.notification/
├── NotificationMcpApp.kt # Application entry
├── server/LocalMcpServer.kt # MCP server (Streamable HTTP protocol)
├── service/
│ ├── NotificationListenerServiceImpl.kt # Notification listener (core entry)
│ ├── KeepAliveService.kt # Foreground keep-alive service
│ ├── WatchdogService.kt # Guard process (mutual guard)
│ └── McpWebSocketManager.kt # WebSocket communication manager
├── filter/
│ ├── NotificationFilterEngine.kt # Notification filtering engine
│ └── DataMaskingEngine.kt # Data desensitization engine
├── diagnostic/
│ ├── DiagnosticEngine.kt # Six-link diagnostic engine
│ ├── DiagnosticReport.kt # Diagnostic report data model
│ └── DiagnosticTool.kt # MCP tool interface
├── db/ # Room database
├── model/ # Data model
├── receiver/BootReceiver.kt # Boot autostart
└── ui/ # Interface layer
├── MainActivity.kt # Status dashboard
└── DiagnosticActivity.kt # Fault diagnosis interface
```
## Technology Stack
| Component | Technology Selection | Version |
|------|---------|------|
| Language | Kotlin | 1.9+ |
| Minimum Version | Android 11 (API 30) | - |
| Target Version | Android 15 (API 35) | - |
| Database | Room (SQLite) | 2.6.1 |
| Network Communication | OkHttp WebSocket | 4.12.0 |
| JSON Processing | Gson | 2.11.0 |
| Coroutine | Kotlin Coroutines | 1.9.0 |
| Protocol | MCP Streamable HTTP (JSON-RPC 2.0) | 2024-11-05 |
## Project Scale
- **Source Files**: 19 Kotlin files
- **Code Quantity**: 3,712 lines (excluding resource files and build configurations)
- **Modules**: 8 functional modules
- **APK Size**: Approximately 14.5 MB (Debug version)
## Frequently Asked Questions
### Q: Why can't I read notifications?
A: The most common reason is that notification access is not enabled, or the battery optimization has killed the app. Check the configuration steps above.
### Q: Can't connect to the MCP server on the computer?
A: Ensure the phone and computer are on the same local network, and replace `127.0.0.1` with the phone's local network IP (e.g., `192.168.1.100`).
### Q: Xiaomi phone notifications always break?
A: MIUI/HyperOS has strict background restrictions; be sure to follow the "Disable Battery Optimization" steps above and set the power-saving strategy to "No restrictions" and enable autostart.
### Q: Which Android versions are supported?
A: Android 11 (API 30) and above, covering over 95% of Android devices in use.
### Q: Are notification data secure?
A: All data is stored in the local database on the phone and will not be uploaded to any cloud. Sensitive information (phone numbers, IDs, bank cards, etc.) will be desensitized before forwarding.
## License
[MIT License](LICENSE) - Free use, modification, and distribution.
```
