Finlynq — Personal Finance App

An open-source personal finance web app with a first-party MCP server. Track income, expenses, budgets, investments, loans, and goals — then query your financial data from Claude, Cursor, Windsurf, or any MCP-compatible AI assistant.

"Track your money here, analyze it anywhere."

License: AGPL v3 · Repo: github.com/finlynq/finlynq · Support: GitHub Sponsors · Ko-fi

Try the Demo

No signup needed — a public demo account is always available on production:

• URL: finlynq.com
• Username: demo (or email [email protected] — login accepts either)
• Password: finlynq-demo

Comes preloaded with 6 months of sample transactions, accounts, budgets, investments, and goals. Data resets nightly at 03:00 UTC, so feel free to change anything.

Connect it to Claude: in Claude → Customize → Connectors → "+" and paste https://finlynq.com/mcp. OAuth handles the rest — no config file.

Running Locally (Windows)

Prerequisites

• Node.js 18+
• PostgreSQL 14+ installed and running (the Windows service postgresql-x64-* should start automatically)
• Git

1. Clone & install

git clone https://github.com/finlynq/finlynq.git
cd finlynq/pf-app
npm install

2. Create your .env file

Copy .env.example to .env and fill in the values:

cp .env.example .env

Minimum required values for local dev:

NODE_ENV=development
APP_URL=http://localhost:3000
DATABASE_URL=postgres://<user>:<password>@localhost:5432/finlynq
PF_JWT_SECRET=<run: openssl rand -hex 32>

Windows tip: If you know a working PostgreSQL user from another project (e.g. epm:epm_dev_password), use those credentials — you just need a user with CREATEDB privilege.

3. Create the database

Open PowerShell in the pf-app directory and run:

# Set your psql path (adjust version number as needed)
$psql = "C:\Program Files\PostgreSQL\16\bin\psql.exe"
$env:PGPASSWORD = "<your-db-password>"

# Create the finlynq database (connect to an existing DB first, e.g. epm_agent_v3 or postgres)
"CREATE DATABASE finlynq;" | & $psql -U <your-user> -h 127.0.0.1 -p 5432 -d <existing-db>

Or open pgAdmin 4 and run:

CREATE DATABASE finlynq;

4. Push the schema

powershell -ExecutionPolicy Bypass -Command "npm run db:push:pg"

Note: On Windows, running npm directly in PowerShell may fail with a script execution policy error. Always prefix with powershell -ExecutionPolicy Bypass -Command "..." or run from Git Bash / Command Prompt.

5. Start the dev server

powershell -ExecutionPolicy Bypass -Command "npm run dev"

App will be available at http://localhost:3000

6. Create your account

Navigate to http://localhost:3000/cloud and click Create Account. Pick a username (3–254 chars, lowercase letters / digits / . @ + _ -) — email is optional.

Heads up: Finlynq encrypts everything with your password. There's no recovery key — if you forget your password, all data is wiped on reset. Adding an email lets you trigger a reset; without one you have no way to regain access.

Running Locally (macOS / Linux)

Prerequisites

• Node.js 18+
• PostgreSQL 14+ (brew install postgresql@16 on macOS, or apt install postgresql on Ubuntu)

Steps

# Clone
git clone https://github.com/finlynq/finlynq.git
cd finlynq/pf-app

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env — set DATABASE_URL and PF_JWT_SECRET

# Create the database (assuming default postgres superuser)
psql -U postgres -c "CREATE DATABASE finlynq;"

# Push schema
npm run db:push:pg

# Start dev server
npm run dev

App will be available at http://localhost:3000

Docker (Self-hosted)

The easiest way to run Finlynq with zero manual setup:

git clone https://github.com/finlynq/finlynq.git
cd finlynq/pf-app

# Copy and configure env
cp .env.example .env
# Edit .env — at minimum set PF_JWT_SECRET

# Start app + PostgreSQL
docker compose up -d

App will be available at http://localhost:3000

The Docker Compose file starts both the app and a PostgreSQL 16 container. Data is persisted in a named volume (postgres_data).

Environment Variables

Tech Stack

MCP Server

Finlynq includes a first-party MCP server with 86 tools for querying and managing your financial data from AI assistants — accounts, transactions, budgets, goals, loans, portfolio, subscriptions, FX rates, rules, splits, bulk edits, and CSV/OFX file imports.

Connect via Claude Desktop (stdio)

Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "finlynq": {
      "command": "npx",
      "args": ["tsx", "/path/to/pf-app/mcp-server/index.ts"],
      "env": {
        "DATABASE_URL": "postgres://epm:epm_dev_password@localhost:5432/finlynq"
      }
    }
  }
}

Connect via Claude Web / Mobile (HTTP)

1. Go to Settings > API Keys in the app and generate a key (prefix pf_)
2. Add the MCP server URL in your AI assistant: https://your-domain.com/api/mcp
3. Use Bearer token auth with your generated key

The .well-known/mcp.json server card at the root enables auto-discovery.

Import Your Data

Go to /import in the app. Supported formats:

All imports include a deduplication engine that fingerprints transactions to prevent duplicates.

Pages

Scripts

Project Structure

pf-app/
  src/
    app/               # 21 pages + 50+ API routes
    components/        # Nav, unlock gate, setup wizard, sparkline, sankey, shadcn/ui
    db/                # Schema (22 tables), PostgreSQL adapter, Drizzle ORM
    lib/               # Business logic (parsers, calculators, AI chat engine, MCP tools)
  mcp-server/          # MCP server v3 (86 tools, stdio + Streamable HTTP)
  drizzle-pg/          # PostgreSQL migration files
  mobile/              # React Native (Expo) mobile app
  docs/                # Getting started, FAQ, mobile setup guide

Contributing

Contributions are welcome! Please read CONTRIBUTING.md first.

• Bug reports → GitHub Issues
• Feature requests → GitHub Discussions
• Pull requests → fork, branch, PR against main

Support the Project

Finlynq is free and open-source (AGPL v3). If it's useful to you, consider supporting development:

• ⭐ Star the repo
• 💛 GitHub Sponsors
• ☕ Ko-fi