Termux Notification List

You can access and monitor Android notifications from Termux through an MCP server. It streams new notifications in real time, lets you fetch current notifications, and supports filtering to help you build AI-assisted workflows that read your device’s notifications securely and efficiently.

How to use

To use this MCP server with an MCP client, you run one of the supported local servers (stdio) or connect via the SSE endpoint for web-based clients. The server streams new notifications when you enable monitoring, and you can pull a snapshot of active notifications at any time. Use filtering to limit results to a specific app package if needed.

How to install

Prerequisites you need before installation:

• Android device with Termux installed

• Termux API app installed and configured

• Node.js 18+ available in Termux

• Proper permissions for notification access

Step 1: Install dependencies in Termux

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

# Grant notification access in Android settings before running the server

Step 2: Install the MCP package

npm install termux-notification-list-mcp

Step 3: (Optional) Build from source

git clone <repository-url>
cdd termux-notification-list-mcp
npm install
npm run build

Step 4: Run the MCP server (stdio) directly or via the built file

npx termux-notification-list-mcp

# Or use the built version directly
node dist/stdio.js

Step 5: Run as an SSE server if you need a web-based client

npx termux-notification-list-mcp-sse

# Or use the built version
node dist/sse.js

Step 6: Configure environment variables (security and access) when deploying

# Bearer token for production use
export MCP_AUTH_TOKEN=your-secure-token

# Optional Basic auth credentials
export MCP_BASIC_USER=admin
export MCP_BASIC_PASS=secure-password

# Allowed CORS origins and server port
export ALLOWED_ORIGINS=http://localhost:3000
export PORT=3000

Additional sections

Configuration and security details help you control who can access the notifications stream. The server supports Bearer token authentication, HTTP Basic Authentication, and query parameter authentication. It also enforces rate limits, validates inputs, and uses secure headers for protection.

Environment variables you may configure:

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)

Client configuration tips: use the following endpoints for SSE clients when running locally

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

Important usage notes: always stop monitoring when you are done to free resources, and ensure you have the necessary permissions to read Android notifications. If you encounter permission errors, grant all required permissions to Termux:API in Android settings and restart Termux.

Troubleshooting common issues include ensuring Termux:API is installed, notification access is granted, and that the server is actually running before attempting to receive events.

Notes on tools and data access

This MCP server exposes a set of tools that let you interact with notifications programmatically. You can start monitoring for new notifications, stop monitoring, and retrieve currently active notifications.

Available tools

waitForNotification

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

stopWaitingForNotification

Stop monitoring for new Android notifications.

getCurrentNotifications

Retrieve all currently active Android notifications with optional filtering by package name and limit.