# 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:
   ```bash
   pkg update && pkg upgrade
   pkg install nodejs termux-api
   ```
3. Grant notification access permissions to Termux:API in Android settings

## Installation

```bash
npm install termux-notification-list-mcp
```

Or build from source:

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

## Usage

### As MCP Server (stdio)

Run the server directly:
```bash
npx termux-notification-list-mcp
```

Or use the built version:
```bash
node dist/stdio.js
```

### As SSE Server

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

```bash
npx termux-notification-list-mcp-sse
```

Or use the built version:
```bash
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:**
```bash
curl -H "Authorization: Bearer your-token" https://your-server:3000/sse
```

**Query Parameter Authentication (for EventSource/SSE):**
```bash
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:**
```bash
curl -u username:password https://your-server:3000/sse
```

Or with explicit header:
```bash
curl -H "Authorization: Basic $(echo -n 'username:password' | base64)" https://your-server:3000/sse
```

**Configuration:**
```bash
# 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:
```bash
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:
   ```bash
   pkg install termux-services
   ```

2. Install the package globally:
   ```bash
   npm install -g termux-notification-list-mcp
   ```

3. Create the service directory:
   ```bash
   mkdir -p $PREFIX/var/service/termux-notification-mcp
   ```

4. Create the run script:
   ```bash
   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:
   ```bash
   sv-enable termux-notification-mcp
   ```

The service will now run automatically and restart if it crashes. You can check its status with:
```bash
source $PREFIX/etc/profile  # If not already done
sv status termux-notification-mcp
```

Stop the service with:
```bash
sv down termux-notification-mcp
```

Restart the service with:
```bash
sv restart termux-notification-mcp
```

### Configuration for MCP Clients

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

```json
{
  "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:**
```typescript
// 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:**
```typescript
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:**
```typescript
// 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:

```typescript
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

```bash
npm run build
```

### Testing

```bash
npm test
```

### Running in Development

```bash
npx tsx app/cli.ts
```

## License

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