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

npm install termux-notification-list-mcp

Or build from source:

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

Usage

As MCP Server (stdio)

Run the server directly:

npx termux-notification-list-mcp

Or use the built version:

node dist/stdio.js

As SSE Server

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

npx termux-notification-list-mcp-sse

Or use the built version:

node dist/sse.js

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:

curl -H "Authorization: Bearer your-token" https://your-server:3000/sse

Query Parameter Authentication (for EventSource/SSE):

curl "https://your-server:3000/sse?token=your-token"
# Or in JavaScript EventSource:
# new EventSource('https://your-server:3000/sse?token=your-token')

HTTP Basic Authentication:

curl -u username:password https://your-server:3000/sse

Or with explicit header:

curl -H "Authorization: Basic $(echo -n 'username:password' | base64)" https://your-server:3000/sse

Configuration:

# Bearer token
export MCP_AUTH_TOKEN=your-secure-token

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

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:

wget https://raw.githubusercontent.com/faisalhakim47/termux-notification-list-mcp/main/setup-service.sh
chmod +x setup-service.sh
./setup-service.sh

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:

source $PREFIX/etc/profile  # If not already done
sv status termux-notification-mcp

Stop the service with:

sv down termux-notification-mcp

Restart the service with:

sv restart termux-notification-mcp

Configuration for MCP Clients

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

{
  "mcpServers": {
    "termux-notifications": {
      "command": "npx",
      "args": ["termux-notification-list-mcp"]
    }
  }
}

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:

// Monitor indefinitely
await client.callTool({
  name: 'waitForNotification',
  arguments: {}
});

// Monitor for 30 seconds
await client.callTool({
  name: 'waitForNotification',
  arguments: { timeout: 30 }
});

stopWaitingForNotification

Stop monitoring for new notifications.

Parameters: None

Example:

await client.callTool({
  name: 'stopWaitingForNotification',
  arguments: {}
});

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:

// Get all notifications
await client.callTool({
  name: 'getCurrentNotifications',
  arguments: {}
});

// Get notifications from a specific app
await client.callTool({
  name: 'getCurrentNotifications',
  arguments: { packageName: 'com.bca.mybca.omni.android' }
});

// Get first 5 notifications
await client.callTool({
  name: 'getCurrentNotifications',
  arguments: { limit: 5 }
});

Notification Data Structure

Each notification contains the following fields:

interface Notification {
  id: number;           // Unique notification ID
  tag: string;          // Notification tag
  key: string;          // Unique notification key
  group: string;        // Notification group
  packageName: string;  // App package name that created the notification
  title: string;        // Notification title
  content: string;      // Notification content/body
  when: string;         // Timestamp when notification was created
}

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

npm run build

Testing

npm test

Running in Development

npx tsx app/cli.ts

License

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