nudlers

Your Personal Finance Command Center for Israeli Banking

Automatically aggregate, categorize, and analyze your finances from all Israeli banks and credit cards in one beautiful dashboard.

Website • Features • Quick Start • Banks & Cards • AI Integration

Why Nudlers?

Managing finances across multiple Israeli banks and credit cards is a nightmare. Different apps, different formats, no unified view. Nudlers solves this.

✨ Features

📊 Unified Financial Dashboard

See all your money in one place. Nudlers aggregates transactions from every Israeli bank and credit card into a single, beautiful interface.

• Multi-View Analytics — Switch between Summary, Budget, Category, Recurring Payment, and Balance Projection views
• Balance Forecasting — Predict your future bank balance based on recurring payments and upcoming credit card charges
• Real-Time Sync — Background syncing keeps your data fresh automatically
• Custom Billing Cycles — Track spending by your credit card billing cycle, not just calendar months
• Installment Tracking — Monitor ongoing installments with remaining payments and amounts

🧠 Intelligent Auto-Categorization

Stop wasting time manually categorizing transactions. Nudlers learns your spending patterns.

3-Phase Smart Categorization:

1. Rule-Based Matching — Custom regex patterns for merchants you define
2. Historical Learning — Remembers how you categorized "Aroma Coffee" and applies it automatically
3. Selective Enrichment — Only fetches additional data when needed, avoiding bot detection

95%+ of transactions are categorized automatically after initial setup

📱 Native WhatsApp Integration

Get your daily financial summary delivered right to WhatsApp — no Twilio, no third-party services.

• Daily Summaries — Wake up to yesterday's spending overview
• Budget Alerts — Know when you're approaching limits
• Group Support — Share summaries with family or partners
• QR Code Setup — Connect in seconds, stays connected forever

🤖 AI-Powered Insights

Ask questions about your finances in plain language using Google Gemini integration.

"What did I spend on groceries this month?"
"Compare my dining expenses to last month"
"Show me my top 10 expenses"

🔌 MCP Integration for AI Assistants

Connect Nudlers directly to Claude Desktop, Cursor, or Claude Code using the Model Context Protocol.

Quick Setup (localhost):

{
  "mcpServers": {
    "nudlers": {
      "command": "npx",
      "args": ["-y", "supergateway@latest", "--sse", "http://localhost:6969/api/mcp"]
    }
  }
}

For remote/hosted instances, replace localhost:6969 with your server URL (see MCP Setup for details).

Now your AI assistant can query your finances, search transactions, and add manual expenses.

💰 Smart Budget Management

Set budgets by category and track them in real-time.

• Visual Progress Bars — See budget consumption at a glance
• Burndown Charts — Daily spending vs. ideal pace visualization
• Historical Comparison — Compare this month to previous months
• Overspend Alerts — Get notified before you exceed limits

📈 Smart Balance Projection

Know your future balance before it happens. Nudlers projects your bank balance for the next 30 days.

• Predictive Analytics — Combines current balances, detected recurring bank transactions, and upcoming credit card settlements.
• Visual Trends — Interactive charts show your balance trajectory and highlight potential risks.
• Manual Overrides — Add manual recurring payments (like rent or direct debits) that the system hasn't detected yet.
• Billing Cycle Awareness — Intelligently accounts for Israeli credit card billing cycles and settlement dates.
• Negative Balance Alerts — Visual indicators catch when your projected balance might drop below zero.

🔒 Bank-Grade Security

Your credentials never leave your machine unencrypted.

• AES-256-GCM Encryption — Industry-standard encryption for all credentials
• Local Processing — No cloud service sees your bank passwords
• Secure by Design — Credentials decrypted only at scraping time
• Memory-Locked Vault — Mandatory security layer. Your master key exists only in RAM. Even if your server is compromised, credentials remain unreadable without your passphrase
• Passkey / Biometric Unlock — Use TouchID, FaceID, or a hardware security key to unlock the vault without typing your passphrase

🔒 Memory-Locked Credentials (Vault)

Nudlers uses a Memory-Locked Vault for all credential encryption. Your master encryption key is "wrapped" with a passphrase and stored in the database. When the application starts, it remains in a "locked" state until you provide the passphrase (or use a passkey) via the UI.

• Non-Persistent: The decrypted key exists only in the application's memory (RAM).
• Auto-Lock: If the app restarts or the server reboots, the vault automatically locks.
• Brute-Force Protected: Key derivation uses scrypt with a custom salt.

How It Works

┌─────────────────────────────────────────────────────────────┐
│                   First-Time Setup                           │
│                                                             │
│  1. User creates a passphrase (8+ chars)                    │
│  2. Random 256-bit master key is generated                  │
│  3. Master key is wrapped with passphrase (scrypt + AES)    │
│  4. Wrapped key stored in database                          │
│  5. Master key held in memory → vault is unlocked           │
│  6. User optionally registers a passkey (biometric)         │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                   Subsequent Unlocks                         │
│                                                             │
│  Option A: Passkey (default when registered)                │
│    1. Browser triggers WebAuthn challenge                    │
│    2. User authenticates with biometric/security key         │
│    3. Server verifies, retrieves encrypted passphrase        │
│    4. Passphrase unwraps master key → vault unlocked         │
│                                                             │
│  Option B: Passphrase                                       │
│    1. User types passphrase                                 │
│    2. Passphrase derives wrapping key via scrypt             │
│    3. Wrapping key decrypts master key → vault unlocked      │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                   Legacy Migration                           │
│                                                             │
│  If upgrading from env-var encryption:                       │
│    1. UI detects NUDLERS_ENCRYPTION_KEY in environment       │
│    2. Prompts user to create a vault passphrase              │
│    3. All credentials re-encrypted with new master key       │
│    4. Legacy env var can be removed after migration          │
└─────────────────────────────────────────────────────────────┘

Setup Guide

• New Installation: Launch Nudlers. The UI automatically detects that the vault is uninitialized and guides you through creating a passphrase. After setup, you'll be prompted to optionally register a passkey for biometric unlock.
• Legacy Migration: If you have NUDLERS_ENCRYPTION_KEY set, the UI will guide you through migrating to the vault. All credentials are re-encrypted in a single transaction. You can remove the env var after migration.

Passkey Management

• Register multiple passkeys (e.g., laptop fingerprint + phone FaceID)
• View and delete individual passkeys in Settings → Vault Security
• When passkeys are registered, the vault defaults to passkey authentication
• You can always switch to passphrase entry by clicking "Use passphrase instead"
• Changing your passphrase invalidates all registered passkeys (re-register required)

Environment Variables for Vault

🍓 Runs Anywhere

From powerful servers to a Raspberry Pi — Nudlers adapts to your hardware.

🏦 Supported Institutions

Banks

Credit Cards

🚀 Quick Start

Prerequisites

• Docker (recommended) OR Node.js 22+ with PostgreSQL 16+
• Google Chrome (for scraping, included in Docker)

Option 1: Docker (Recommended)

# Clone the repository
git clone https://github.com/enudler/nudlers.git
cd nudlers

# Configure environment
cp .env_example .env
# Edit .env with your database password

# Start everything
docker-compose up -d

Open http://localhost:3000 and start adding your accounts!

Option 2: NAS / Server (Pre-built Image)

For Synology, QNAP, or any server with Docker:

# Create deployment directory
mkdir nudlers && cd nudlers

# Download production configs
curl -O https://raw.githubusercontent.com/enudler/nudlers/main/docker-compose.prod.yaml
curl -O https://raw.githubusercontent.com/enudler/nudlers/main/.env_example

# Configure and start
cp .env_example .env
# Edit .env with your settings
docker-compose -f docker-compose.prod.yaml up -d

Supports both linux/amd64 and linux/arm64 architectures.

Option 3: Manual Installation

# Clone and install
git clone https://github.com/enudler/nudlers.git
cd nudlers/app
npm install

# Configure PostgreSQL and .env file
# See Environment Variables section below

# Run
npm run dev

⚙️ Configuration

Environment Variables

Application Settings

All settings are configurable through the Settings UI (gear icon in navigation):

🤖 AI Integrations

Built-in AI Assistant

The built-in chat uses Google Gemini to answer questions about your finances:

• "What's my budget status for groceries?"
• "Show me all transactions from Rami Levy"
• "How much did I spend on dining this month vs last month?"

Setup: Add your GEMINI_API_KEY in Settings or .env

MCP for Claude Desktop / Cursor / Claude Code

Nudlers exposes a Model Context Protocol (MCP) endpoint that AI assistants can use directly to query and manage your finances.

Setup for Claude Desktop

Add to ~/.config/claude/claude_desktop_config.json (macOS/Linux) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "nudlers": {
      "command": "npx",
      "args": ["-y", "supergateway@latest", "--sse", "http://localhost:6969/api/mcp"]
    }
  }
}

Setup for Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "nudlers": {
      "command": "npx",
      "args": ["-y", "supergateway@latest", "--sse", "http://localhost:6969/api/mcp"]
    }
  }
}

Setup for Claude Code

Add to your project's .mcp.json or global ~/.claude/mcp.json:

{
  "mcpServers": {
    "nudlers": {
      "command": "npx",
      "args": ["-y", "supergateway@latest", "--sse", "http://localhost:6969/api/mcp"]
    }
  }
}

Remote / Hosted Setup

For Nudlers running on a remote server, NAS, or Docker container, replace the URL:

{
  "mcpServers": {
    "nudlers": {
      "command": "npx",
      "args": ["-y", "supergateway@latest", "--sse", "https://your-server.com/api/mcp"]
    }
  }
}

Examples:

• Docker on local network: http://192.168.1.100:3000/api/mcp
• Synology NAS: http://nas.local:3000/api/mcp
• Cloud server with HTTPS: https://nudlers.yourdomain.com/api/mcp

Note: For HTTPS, ensure your server has a valid SSL certificate. For local network access, use HTTP with your server's IP address.

Available Tools

Example Queries

Once connected, you can ask your AI assistant:

• "What did I spend on groceries this month?"
• "Show me my budget status"
• "Add a manual expense: Coffee at Aroma, 25 ILS, today, category Dining"
• "What are my recurring payments?"
• "Search for transactions from Rami Levy"
• "Compare my spending by category"

Troubleshooting MCP

Connection refused:

# Verify Nudlers is running
curl http://localhost:6969/api/ping
# Should return: {"status":"ok"}

Test the MCP endpoint:

# This should return SSE headers and keep connection open
curl -N http://localhost:6969/api/mcp

"supergateway" not found:

# Ensure npx is available (comes with Node.js)
npx --version

# Or install supergateway globally
npm install -g supergateway

Wrong port:

• Development mode uses port 6969
• Docker production typically uses port 3000
• Check your docker-compose.yaml for port mappings

Firewall issues (remote access):

• Ensure the port is accessible from your client machine
• For Docker: check port mappings in docker-compose.yaml
• For NAS: check firewall and port forwarding settings

💡 Smart Categorization Explained

Nudlers uses a unique 3-phase approach to achieve high accuracy while avoiding bot detection:

┌─────────────────────────────────────────────────────────────────────┐
│                        PHASE 1: Hybrid Scrape                        │
│  Fetch transactions WITHOUT categories (avoids bot detection)        │
└────────────────────────────────┬────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────────┐
│                     PHASE 2: Local Matching                          │
│  ┌──────────────────┐    ┌──────────────────────────────────────┐   │
│  │   Custom Rules   │ -> │  If no match, check historical cache │   │
│  │  (Regex-based)   │    │   "Aroma" -> "Dining" (from history) │   │
│  └──────────────────┘    └──────────────────────────────────────┘   │
└────────────────────────────────┬────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────────┐
│                  PHASE 3: Selective Enrichment                       │
│  Only for remaining uncategorized: targeted API calls (low risk)     │
└─────────────────────────────────────────────────────────────────────┘

This approach provides:

• Speed — Most transactions categorized instantly from cache
• Accuracy — 95%+ categorization rate
• Safety — Minimal API calls prevent account lockouts

📱 WhatsApp Integration

How It Works

Nudlers uses a headless browser to connect to WhatsApp Web — no third-party services required.

Setup

1. Go to Settings → WhatsApp Daily Summary
2. Click Start WhatsApp Service
3. Scan the QR code with your phone (WhatsApp → Linked Devices)
4. Configure recipients (phone numbers or group IDs)
5. Set your preferred delivery time

Docker Configuration

For Docker deployments, add these to your docker-compose.yaml:

services:
  nudlers-app:
    volumes:
      - whatsapp-data:/app/.wwebjs_auth  # Persist session
    cap_add:
      - SYS_ADMIN
    security_opt:
      - seccomp=unconfined
    shm_size: '2gb'

volumes:
  whatsapp-data:

🛠️ Troubleshooting

"Block Automation" Errors (Isracard/Max/Amex)

These vendors have aggressive bot detection. Solutions:

1. Use Low Resource Mode — Set RESOURCE_MODE=low to reduce browser footprint and memory usage
2. Reduce Sync Days — Lower sync_days_back to 7-14 days
3. Manual Login — Log in to the vendor website once to clear notices
4. Wait — If blocked, wait 24 hours before retrying

Chrome Not Found

For custom environments:

PUPPETEER_EXECUTABLE_PATH=/usr/bin/google-chrome

WhatsApp QR Code Not Appearing

1. Check browser capabilities in Docker config
2. Ensure shm_size is at least 1gb
3. Check logs: docker-compose logs -f nudlers-app

🏗️ Architecture

nudlers/
├── app/                          # Next.js application
│   ├── components/               # React UI components
│   │   ├── CategoryDashboard/    # Main dashboard views
│   │   ├── Layout.tsx            # App shell with navigation
│   │   └── ...
│   ├── pages/
│   │   ├── api/                  # 55 API endpoints
│   │   │   ├── transactions/     # Transaction CRUD
│   │   │   ├── scrapers/         # Scraper control
│   │   │   ├── reports/          # Financial reports
│   │   │   ├── mcp.ts            # MCP integration endpoint
│   │   │   └── ...
│   │   └── index.tsx
│   ├── scrapers/                 # Bank scraper logic
│   ├── utils/                    # Shared utilities
│   └── styles/                   # Theming (light/dark mode)
├── docker-compose.yaml           # Local development
├── docker-compose.prod.yaml      # Production deployment
└── db-init/                      # Database initialization

Tech Stack

🧪 Development

cd app

# Install dependencies
npm install

# Start development server (port 6969)
npm run dev

# Run tests
npm run test

# Run linter
npm run lint

# Start Storybook (port 6006)
npm run storybook

🔄 Updating

Docker

docker-compose pull
docker-compose up -d

Manual

git pull
cd app
npm install
npm run build
npm start

Database migrations run automatically on startup.

📄 License

Polyform Noncommercial License 1.0.0

Free for personal, non-commercial use. For commercial licensing, please contact the author.

See LICENSE for full terms.

🙏 Credits

• Bank Scraping: israeli-bank-scrapers
• UI Framework: Material-UI
• WhatsApp Integration: whatsapp-web.js

Take control of your Israeli finances.
nudlers.com • Star on GitHub • Report Issues