Norman

MCP server: norman-finance

{
  "type": "http",
  "url": "https://mcp.norman.finance/mcp"
}

Review and categorize uncategorized bank transactions, match them with invoices, and verify bookkeeping entries. Use when the user wants to review transactions, categorize expenses, do bookkeeping, or reconcile their bank account.

Help the user categorize and organize their bank transactions:

1. **Fetch uncategorized transactions**: Call `search_transactions` to find transactions that need attention. Look for unverified or uncategorized entries.

2. **Smart categorization**: For each transaction, suggest a category based on:
   - The transaction description / reference text
   - The counterparty name
   - The amount and pattern (recurring = likely subscription)
   - Similar past transactions

3. **Update transactions**: Use `categorize_transaction` to assign the correct bookkeeping category (SKR04 chart of accounts for German businesses).

4. **Invoice matching**: When a transaction looks like an incoming payment:
   - Call `list_invoices` to find matching unpaid invoices (by amount or client)
   - Use `link_transaction` to connect the payment to the invoice

5. **Document attachment**: Remind the user to attach receipts for expenses:
   - Use `upload_bulk_attachments` for multiple receipts
   - Use `link_attachment_transaction` to connect receipts to transactions

6. **Verification**: After categorizing, use `change_transaction_verification` to mark transactions as verified.

Present transactions in batches of 10-15 for manageable review. Show: Date, Amount, Description, Suggested Category.

Create and optionally send a new invoice to a client. Use when the user wants to invoice someone, bill a client, or create a new Rechnung.

Help the user create and send an invoice step by step:

1. **Identify the client**: If a client name is provided in `$ARGUMENTS`, call `list_clients` and find the matching client. If ambiguous, ask the user to clarify. If no client exists, offer to create one with `create_client`.

2. **Gather invoice details**: Collect the following information (ask for anything not provided):
   - Line items: description, quantity, unit price, VAT rate (default 19% for Germany)
   - Invoice date (default: today)
   - Due date / payment terms (default: 14 days)
   - Any notes or special terms

3. **Create the invoice**: Call `create_invoice` with all gathered details. Use the correct client_id from step 1.

4. **Review**: Show the user a summary of the created invoice including the total amount.

5. **Send**: Ask the user if they want to send the invoice now. If yes, call `send_invoice` to email it to the client.

Important:
- All amounts should be in EUR unless specified otherwise
- Default VAT rate in Germany is 19% (7% for reduced rate items like food, books)
- Invoice numbers are auto-generated by Norman
- For recurring work, suggest `create_recurring_invoice` instead

Generate a detailed expense breakdown by category for a given period. Use when the user asks for an expense report, spending summary, Ausgabenübersicht, cost analysis, or wants to understand where their money is going.

Generate a comprehensive expense report for the user:

## Step 1: Gather data
- Call `search_transactions` for the specified period (default: last month)
- Filter for outgoing transactions (expenses only, exclude income)
- Call `get_company_balance` for current balance context

## Step 2: Categorize and group
Group expenses by bookkeeping category. For each category show:
- Category name
- Total amount (EUR)
- Number of transactions
- Percentage of total expenses

Present as a ranked list, largest category first.

## Step 3: Top vendors
List the top 10 vendors/payees by total spend:
- Vendor name
- Total amount
- Number of transactions
- Average transaction amount

## Step 4: Trends and insights
If the user asks for a longer period (quarter or year), provide:
- Month-over-month comparison of total expenses
- Categories that increased or decreased significantly
- Recurring vs. one-time expenses
- Largest single transactions in the period

## Step 5: Comparison (if possible)
If data is available for the previous equivalent period:
- Total expenses this period vs. last period
- Percentage change
- Categories with the biggest increase/decrease
- Flag any unusual or new expense categories

## Presentation format
Structure the report clearly:

```
Expense Report: [Period]
========================
Total Expenses: X,XXX.XX EUR

By Category:
  1. [Category]     X,XXX.XX EUR  (XX%)  [N transactions]
  2. [Category]       XXX.XX EUR  (XX%)  [N transactions]
  ...

Top Vendors:
  1. [Vendor]       X,XXX.XX EUR  [N transactions]
  2. [Vendor]         XXX.XX EUR  [N transactions]
  ...

Key Insights:
  - [Notable finding]
  - [Notable finding]
```

Keep amounts in EUR. Use clear formatting for readability. Offer to drill down into any specific category if the user wants more detail.

Get a complete financial overview of the business including balance, recent transactions, outstanding invoices, and upcoming tax obligations. Use when the user asks about their financial status, dashboard, summary, or "how is my business doing?

Provide a comprehensive financial overview by gathering data from multiple sources:

1. **Company details**: Call `get_company_details` to get the business name and context
2. **Current balance**: Call `get_company_balance` to show available funds
3. **Recent transactions**: Call `search_transactions` with a recent date range (last 30 days) to show cash flow
4. **Outstanding invoices**: Call `list_invoices` and highlight unpaid or overdue ones
5. **Tax status**: Call `get_vat_next_report` to show upcoming tax deadlines and `get_company_tax_statistics` for the tax overview

Present the information in a clear, structured format:

- Start with the company name and current balance
- Show a brief income vs expenses summary from recent transactions
- List any overdue invoices that need attention
- Highlight upcoming tax deadlines
- End with actionable recommendations (e.g., "You have 3 overdue invoices totaling X EUR")

Use EUR currency formatting. Be concise but thorough.

Find and attach missing receipts for business transactions. Search Gmail, email, or other sources for invoices and receipts, then upload them to Norman. Use when the user asks about missing receipts, Belege, attaching documents, or finding invoices from emails.

Help the user find and attach receipts to their transactions:

## Step 1: Identify transactions missing receipts
- Call `search_transactions` to find recent transactions
- Call `list_attachments` to check which transactions already have receipts attached
- Present a list of transactions that are missing receipts, sorted by amount (largest first)

## Step 2: Search for receipts
Guide the user to find receipts from various sources:

**Gmail / Email:**
- Suggest searching Gmail with queries like:
  - `from:{vendor} subject:receipt` or `from:{vendor} subject:invoice`
  - `subject:Rechnung from:{vendor}`
  - `subject:Bestellbestätigung` (order confirmation)
  - `has:attachment after:{date} {vendor name}`
- For common vendors, suggest specific search terms:
  - AWS: `from:aws subject:"invoice available"`
  - Google: `from:payments-noreply@google.com`
  - Apple: `from:apple subject:receipt`
  - Amazon: `from:auto-confirm@amazon subject:Bestellung`

**Other sources:**
- Check vendor portals (suggest logging into the vendor's website to download invoices)
- Check cloud storage (Google Drive, Dropbox) for scanned receipts
- Check photo library for photos of paper receipts

## Step 3: Upload and attach
Once the user has the receipt files:
- Use `upload_bulk_attachments` to upload multiple receipts at once
- Use `create_attachment` for individual receipts with metadata (vendor, date, amount)
- Use `link_attachment_transaction` to connect each receipt to its matching transaction

## Step 4: Verify
- After attaching, use `change_transaction_verification` to mark transactions as verified
- Show a summary: how many receipts were found, attached, and how many are still missing

Tips:
- In Germany, receipts must be kept for 10 years (Aufbewahrungspflicht)
- Digital copies are legally accepted (GoBD-compliant) when stored properly
- Prioritize receipts for expenses over 250 EUR (required for Vorsteuerabzug)

Manage business clients - list, search, create, or update client information. Use when the user mentions clients, contacts, customers, Kunden, or needs to manage their client database.

Help the user manage their client database:

## Listing and searching
- Call `list_clients` to show all clients
- Present results in a clean table format: Name, Email, Phone, Outstanding balance

## Creating a new client
When creating a client with `create_client`, gather:
- **Required**: Client name (company or individual)
- **Recommended**: Email, phone, address (street, city, postal code, country)
- **Optional**: Tax ID (Steuernummer), VAT ID (USt-IdNr.), payment terms, notes
- For German businesses: ask about Kleinunternehmer status if relevant

## Updating a client
- Call `get_client` first to show current details
- Call `update_client` with only the fields that need changing
- Confirm changes with the user before updating

## Best practices
- Always verify client details before creating invoices
- For EU clients, the VAT ID (USt-IdNr.) is important for reverse charge invoices
- Suggest cleaning up duplicate clients if detected

Perform a complete monthly financial reconciliation - review all transactions, match invoices, check outstanding payments, and prepare for tax filing. Use when the user wants to close the month, do monthly bookkeeping, or perform a Monatsabschluss.

Guide the user through a complete monthly reconciliation:

## Step 1: Transaction Review
- Call `search_transactions` for the specified month (or last month if not specified)
- Identify uncategorized transactions
- For each batch, suggest categories and let the user confirm
- Use `categorize_transaction` to assign the correct bookkeeping category

## Step 2: Finalize Transactions
- After all transactions are categorized, verify each one using `change_transaction_verification`
- Mark every transaction for the period as verified so the month can be closed
- If any transaction has missing information (no receipt, unclear category), flag it for the user before verifying
- Present a count: "X of Y transactions verified for [month]"

## Step 3: Invoice Reconciliation
- Call `list_invoices` to find invoices from the period
- Cross-reference with incoming payments in transactions
- Use `link_transaction` to match payments to invoices
- Flag any overdue unpaid invoices and suggest sending reminders via `send_invoice_overdue_reminder`

## Step 4: Document Check
- Call `list_attachments` for the period
- Identify transactions without attached receipts (especially expenses)
- Remind the user to upload missing receipts with `upload_bulk_attachments`
- Use `link_attachment_transaction` to connect any newly uploaded receipts

## Step 5: Tax Preparation
- Call `get_company_tax_statistics` for the period overview
- Call `get_vat_next_report` to check if a VAT report is due
- If due, call `generate_finanzamt_preview` to show the draft
- Only submit with explicit user confirmation via `submit_tax_report`

## Step 6: Summary
Present a closing summary:
- Total income and expenses for the month
- Number of invoices sent vs. paid
- Outstanding receivables
- VAT liability
- Any action items remaining

Be thorough but keep each step interactive - wait for user confirmation before proceeding.

Find overdue invoices and send payment reminders (Zahlungserinnerungen / Mahnungen) to clients. Use when the user asks about unpaid invoices, overdue payments, payment reminders, Mahnung, or chasing payments.

Help the user manage overdue invoices and send payment reminders:

## Step 1: Find overdue invoices
- Call `list_invoices` to get all invoices
- Filter for invoices that are past their due date and still unpaid
- If `$ARGUMENTS` specifies a client name, filter to that client only
- Present a summary table: Client, Invoice #, Amount, Due Date, Days Overdue

## Step 2: Prioritize
Group overdue invoices by severity:
- **Gentle reminder** (1-14 days overdue): First reminder, friendly tone
- **Second reminder** (15-30 days overdue): Firmer tone, reference original due date
- **Final notice** (30+ days overdue): Urgent, mention potential consequences

## Step 3: Review before sending
For each overdue invoice (or batch per client):
- Show the invoice details: amount, due date, days overdue
- Show the client's contact info from `get_client`
- Let the user decide whether to send a reminder or skip

## Step 4: Send reminders
- Use `send_invoice_overdue_reminder` for each approved reminder
- Wait for user confirmation before each send

## Step 5: Summary
Present a final report:
- Total overdue amount across all clients
- Number of reminders sent
- Any invoices the user chose to skip (and why)
- Suggest scheduling a follow-up check in 7 days

Important:
- ALWAYS let the user review and approve each reminder before sending
- Never send reminders automatically without explicit confirmation
- In Germany, a Mahnung (formal dunning letter) has legal implications - make sure the user is aware
- Suggest checking if a payment was recently received but not yet linked (use `search_transactions`)

Scan transactions for potentially missed tax deductions and suggest proper categorization. Use when the user asks about saving taxes, Steueroptimierung, deductible expenses, Betriebsausgaben, or wants to check if they are missing any write-offs.

Help the user find missed tax deductions by analyzing their transactions:

## Step 1: Gather data
- Call `search_transactions` for the specified period (default: current year)
- Call `get_company_details` to understand the business type
- Call `list_tax_settings` to check VAT status and tax regime

## Step 2: Scan for common deductions
Review each transaction and flag potential deductions that may be miscategorized or unverified. Look for these common German freelancer/small business deductions:

**Home office (Arbeitszimmer):**
- Rent, electricity, internet, heating proportional to office space
- Office furniture, equipment, monitors, desks

**Technology & software:**
- SaaS subscriptions (Adobe, Google Workspace, Slack, hosting)
- Computer hardware (fully deductible if under 1000 EUR net, otherwise depreciated)
- Phone and mobile plans (business portion)

**Travel & transportation (Reisekosten):**
- Public transport, fuel, car maintenance
- Hotels for business trips
- Meals during business travel (Verpflegungspauschale: 14 EUR/28 EUR per day)

**Professional development:**
- Courses, certifications, books, conferences
- Professional memberships and associations

**Insurance & financial:**
- Professional liability insurance (Berufshaftpflicht)
- Business bank account fees
- Tax advisor fees (Steuerberater)

**Marketing & client acquisition:**
- Advertising, domain names, hosting
- Business cards, printed materials
- Client gifts (up to 35 EUR per person per year)

## Step 3: Suggest corrections
For each potentially missed deduction:
- Show the transaction: date, amount, description, current category
- Suggest the correct SKR04 category
- Explain why it qualifies as a deduction
- Use `categorize_transaction` to recategorize if the user confirms

## Step 4: Estimate impact
Present a summary:
- Number of transactions reviewed
- Number of potential missed deductions found
- Estimated additional deductible amount (EUR)
- Approximate tax savings (rough estimate using ~30-42% marginal rate for Einkommensteuer + Soli)

Tips:
- Items under 1000 EUR net (GWG - Geringwertige Wirtschaftsgüter) can be fully deducted in the purchase year
- Items over 1000 EUR must be depreciated over their useful life (AfA)
- Mixed-use items (e.g., phone) should only claim the business portion
- Keep receipts for all deductions - suggest attaching any missing ones

Review and manage German tax reports including VAT (Umsatzsteuer), income tax prepayments, and Finanzamt submissions. Use when the user asks about taxes, Steuern, VAT, USt, Finanzamt, or tax filing.

Help the user with their German tax obligations:

1. **Overview**: Call `list_tax_reports` to see all tax reports and their statuses (draft, validated, submitted)

2. **Next deadline**: Call `get_vat_next_report` to show the next upcoming VAT filing deadline

3. **Specific report**: If the user asks about a specific period, call `get_tax_report` with the report ID to see details including:
   - Reporting period
   - Revenue and VAT amounts
   - Status (draft, ready, submitted)
   - Finanzamt submission status

4. **Preview before submission**: Call `generate_finanzamt_preview` to show the user exactly what will be sent to the Finanzamt. Let them review all figures.

5. **Submit**: Only when the user explicitly confirms, call `submit_tax_report` to file with the Finanzamt via ELSTER.

6. **Tax settings**: Call `list_tax_settings` to review VAT registration, filing frequency, and other tax configuration.

Important warnings:
- ALWAYS show a preview before submitting to the Finanzamt
- Tax submissions are IRREVERSIBLE - make sure the user explicitly confirms
- Remind the user of filing deadlines (monthly: 10th of following month, quarterly: 10th of following quarter month)
- If tax numbers need validation, use `validate_tax_number`