Termux Notification List MCP Server

A Model Context Protocol (MCP) server that provides access to Android notifications via Termux, enabling AI agents to monitor and read Android notifications in real-time.

Features

• Real-time notification monitoring: Stream new notifications as they arrive

• Current notification retrieval: Get a snapshot of all active notifications

• Filtering capabilities: Filter notifications by package name or limit results

• Clean notification data: Structured JSON output with all notification metadata

Prerequisites

• Android device with Termux installed

• Termux API app installed and configured

• Node.js 18+ in Termux environment

• Proper permissions for notification access

Setup Termux Environment

1. Install Termux and Termux:API from F-Droid or Google Play

2. Install required packages in Termux:

   pkg update && pkg upgrade pkg install nodejs termux-api

3. Grant notification access permissions to Termux:API in Android settings

Installation

Or build from source:

Usage

As MCP Server (stdio)

Run the server directly:

Or use the built version:

As SSE Server

The package can also run as an SSE server for web-based MCP clients:

Or use the built version:

The SSE server listens on port 3000 by default, configurable via PORT environment variable.

Security Configuration

The SSE server includes several security features for remote access:

Environment Variables

• MCP_AUTH_TOKEN: Bearer token for authentication (required for production)

• MCP_BASIC_USER: Username for HTTP Basic Authentication

• MCP_BASIC_PASS: Password for HTTP Basic Authentication

• ALLOWED_ORIGINS: Comma-separated list of allowed CORS origins (default: http://localhost:3000)

• PORT: Server port (default: 3000)

Authentication

The server supports Bearer token, HTTP Basic Authentication, and query parameter authentication:

Bearer Token Authentication:

Query Parameter Authentication (for EventSource/SSE):

HTTP Basic Authentication:

Or with explicit header:

Configuration:

You can enable both authentication methods simultaneously for maximum compatibility.

Security Features

• Rate Limiting: 100 requests per 15 minutes per IP

• CORS Protection: Configurable allowed origins

• Input Validation: JSON payload validation

• Helmet Security Headers: XSS protection, HSTS, CSP

• TLS 1.2+: Strong cipher suites for HTTPS

• Error Handling: Secure error responses without information leakage

Running as a Background Service in Termux

To run the SSE server indefinitely as a background service using runit:

Automated Setup

Run the provided setup script:

Note: After running the setup script, restart your Termux session or run source $PREFIX/etc/profile to use service management commands.

Manual Setup

1. Install termux-services:

   pkg install termux-services

2. Install the package globally:

   npm install -g termux-notification-list-mcp

3. Create the service directory:

   mkdir -p $PREFIX/var/service/termux-notification-mcp

4. Create the run script:

   cat > $PREFIX/var/service/termux-notification-mcp/run << 'EOF' #!/bin/sh exec termux-notification-list-mcp-sse EOF chmod +x $PREFIX/var/service/termux-notification-mcp/run

5. Enable and start the service:

   sv-enable termux-notification-mcp

The service will now run automatically and restart if it crashes. You can check its status with:

Stop the service with:

Restart the service with:

Configuration for MCP Clients

Add to your MCP client configuration (e.g., Claude Desktop):

For SSE clients, connect to http://localhost:3000/sse

Available Tools

waitForNotification

Start monitoring for new Android notifications. Returns immediately and sends notifications via server events as they arrive.

Parameters:

• timeout (optional): Number of seconds to monitor before automatically stopping

Example:

stopWaitingForNotification

Stop monitoring for new notifications.

Parameters: None

Example:

getCurrentNotifications

Retrieve all currently active Android notifications.

Parameters:

• packageName (optional): Filter notifications by specific app package name

• limit (optional): Limit the number of notifications returned (1-100)

Example:

Notification Data Structure

Each notification contains the following fields:

Server Events

The server sends real-time notifications via MCP's notification system:

• New Notification Event: Sent when waitForNotification is active and a new notification arrives

• Error Events: Sent when monitoring encounters errors

Best Practices

1. Monitoring Lifecycle: Always call stopWaitingForNotification when done monitoring to free resources

2. Error Handling: Handle cases where termux-notification-list command is not available

3. Privacy: Be mindful that this tool can access all Android notifications - implement appropriate access controls

4. Performance: Use limit parameter when you only need recent notifications

Security Considerations

• This server provides access to all Android notifications, which may contain sensitive information

• Ensure proper authentication and authorization when deploying

• Consider implementing filtering or access controls for production use

• Follow the principle of least privilege

Troubleshooting

termux-notification-list command not found

• Ensure Termux:API is installed

• Verify termux-api package is installed: pkg install termux-api

• Check that notification permissions are granted in Android settings

No notifications received

• Verify Termux:API has notification access permissions

• Check that there are active notifications to read

• Ensure the monitoring is actually started with waitForNotification

Permission denied errors

• Grant all requested permissions to Termux:API in Android settings

• Restart Termux after granting permissions

Development

Building

Testing

Running in Development

License

FSL-1.1-MIT - See LICENSE file for details.