Norman Finance — AI Bookkeeping, Accounting & Taxes

What you can do

Invoicing — Create and edit invoices, quotes, and recurring schedules, including document templates, line discounts, units, service dates and payment links. Polish invoice items preserve VAT codes. German workflows include ZUGFeRD, Stornorechnung, Rechnungskorrektur and Lieferschein.

Client emails and reminders — Send invoices with the company's own email wording and CC recipients, see their delivery status, switch automatic payment reminders on for an invoice, and set the reminder rule (days and dunning fees per level)

Bookkeeping — Categorize transactions, match receipts, and verify entries

Polish accounting — Inspect a JDG's KPiR and explain why an operation is included or excluded. For sp. z o.o. using PL_FULL, read the journal, chart of accounts, account sheets, trial balance and prepared financial statements. Preview accounting-export compatibility for General, Optima and EPP formats. See Polish MCP tools and examples.

DATEV — Generate German DATEV EXTF exports with SKR03 or SKR04 for your Steuerberater. DATEV support includes complete Ledger export, standalone EXTF reading and checks before accountant handoff.

Automation rules — "Always book Telekom to Internet costs": preview, create, and manage rules that categorize matching transactions automatically

Workflows — "Close August for me": Norman runs month-end close, bank reconciliation, VAT-return readiness, invoice-to-payment and client document requests on its own servers, stops only to ask you something, and can run them by itself every month; answer its questions and see what the agents did this week from your AI client

Client Management — Maintain your client database and contact details

Products & Services — Keep a catalog of what you sell, with prices, VAT rates and units, and fill invoice lines from it

Tax reports — For Germany, generate Finanzamt previews and submit supported returns after confirmation. For Poland, inspect JPK sales and purchases, PIT/ZUS or CIT estimates, and existing JPK/PIT filing status and UPO availability. Polish signing and submission are not exposed as MCP tools.

German payroll — Run the monthly Lohnabrechnung of a GmbH/UG (Max plan): calculate and approve the month, see social insurance per Krankenkasse and the Minijob-Zentrale, save the Beitragsnachweis estimate, file the Lohnsteuer-Anmeldung, correct an approved month, and get payslips and the Lohnkonto as download links. Steuer-IDs, insurance numbers and bank details stay in the Norman app

Company Overview — Check your balance, revenue, and financial health at a glance

Company Formation — Found a German GmbH or UG: collect the founders' data, check the name against the Handelsregister, generate the founding documents (Musterprotokoll, Gesellschafterliste), match with a notary, and track every step through to registration

Documents — Upload and attach receipts, invoices, and supporting files

create_attachment.file_url, bulk file_urls, and structured document imports accept HTTP(S) download links, including unexpired presigned S3 URLs with query parameters. Pass the entire link unchanged; the file host must accept the request without additional authorization headers. The URL downloader has no domain allowlist, URL-length cap, or explicit file-size cap. Its connect/read timeout is 30 seconds (not a total download deadline). The separate browser upload route defaults to 50 MiB, configurable with MCP_UPLOAD_MAX_SIZE; API file validation still applies.

URL download failures return an error message and code: download_http_error (with http_status), download_timeout, download_network_error, download_storage_error, or download_error. A 403 from the file host can mean an expired or rejected signature; obtain a fresh link and check the host response. Bulk uploads include download_errors for failed URLs, indexed within file_urls followed by URL entries from the deprecated file_paths alias; successfully fetched files are still uploaded. Structured imports report errors per document. Download errors omit signed URLs, and temporary downloads are cleaned up after use or cancellation.

Market-specific capabilities

Select the company before working with its books. company://current identifies the selected company, country, accounting currency, legal form and chart of accounts. Use list_companies and switch_company when working across companies; the conversation language does not determine the tax jurisdiction.

Polish support is in soft launch. Availability depends on the selected company's setup, plan, permissions and deployed Norman API. Polish tools check company country and book type; German procedures such as DATEV export, ELSTER, payroll and incorporation reject Polish companies.

The Polish MCP tools cover books, diagnostics, export previews and existing filing state. They do not create manual Polish journal postings, generate or close annual statements, sign returns or submit them to MF/KRS. An XML download is not a filing receipt: report success only from confirmed acceptance and UPO.

Poland: KPiR, full books and JPK

The Polish accounting guide lists all 14 dedicated tools, their arguments and workflow limits. Shared invoice, transaction and asset tools also support Polish VAT codes and depreciation inputs.

• JDG: inspect monthly or annual KPiR, then explain an individual operation's inclusion or exclusion with get_polish_tax_book_operation.
• Spółki: follow journal entries back to their source, inspect account balances and review an existing financial statement's workbook, notes and XML issues.
• VAT: compare JPK sales, purchases, totals and exclusions with the underlying operations. Preserve vat_code; a numeric 0% rate alone does not identify exemption, reverse charge or a supply outside Poland.
• Accountant handoff: preview General, Optima or EPP export compatibility and review blockers before preparing the handoff in Norman.

Try asking:

• "Pokaż KPiR mojej JDG za wrzesień i wyjaśnij, dlaczego ten koszt nie trafił do księgi."
• "Pokaż zestawienie obrotów i sald mojej spółki za trzeci kwartał."
• "Sprawdź rejestr JPK_V7: sprzedaż, zakupy i pominięte operacje."
• "Sprawdź status wysyłki JPK i dostępność UPO. Niczego nie wysyłaj."

KPiR and tax-estimate reads can synchronize derived records in the API; these tools declare readOnlyHint=false. The API remains responsible for calculations, eligibility and access checks.

Invoice appearance and updates

Use list_invoice_templates to discover the templates, appearance controls and the active company's plan access. Use get_invoice_settings to read its logo and saved defaults.

create_invoice, create_recurring_invoice and create_offer accept document_design, for example:

{"template": "sovereign", "logoSize": 75, "textSize": "medium", "spacing": "compact", "tableBorders": "grid"}

Omit document_design, font, and color_schema to inherit saved branding. On create, a partial design uses that template's defaults. Paid templates require an active subscription.

Use update_invoice for an invoice or quote, update_recurring_invoice for a schedule, and update_invoice_settings for future document defaults. Their typed changes object accepts camelCase or snake_case field names. Unset fields stay unchanged; explicit false, 0, empty strings and valid nulls keep their meaning. A partial document design keeps the document's other saved controls; changing its template starts from that template's defaults. Keep existing line IDs when editing lines. Rates use minor currency units; the API calculates totals. Only set isToSend when sending is intended.

Use cancel_invoice, create_credit_note and create_delivery_note for documents derived from an existing invoice or an approved quote; each links back to its source, and a cancelled invoice is read-only afterwards. duplicate_invoice copies an invoice or quote into a fresh draft without a link. API keys need read_invoices for template/settings reads and write_invoices for edits. Settings updates use the invoice-specific endpoint and cannot edit other company fields. Deploy the matching invoice API endpoints before deploying this MCP version.

Client emails and payment reminders

send_invoice and send_invoice_overdue_reminder use the company's email template when subject and body are left out; additional_emails go out as CC, and the company's own copy follows its setting unless is_send_to_company is given. list_invoice_emails returns every email about a document with its delivery status and the reminder the rule sends next. A send that fails at once returns an error with the reason; otherwise email.status is sent, or queued while Norman retries. A dunning fee is shown in the reminder with the total and is paid by bank transfer: a reminder with a fee has no online payment button.

Automatic reminders are off until autoReminders is true on the invoice (create_invoice, create_recurring_invoice, or update_invoice, also after the invoice was issued); remindersPaused stops them for one invoice and skip_invoice_reminder stops one planned reminder. remindersActive on an invoice says whether Norman reminds by itself right now. The company's rule and wording live in get_invoice_email_settings / update_invoice_email_settings and list_invoice_email_templates / save_invoice_email_template / reset_invoice_email_template. settings_on_overdue is kept for older integrations and sends nothing. These tools need the invoice email endpoints of the API to be live before this MCP version is deployed.

DATEV MCP support: EXTF, SKR03 and SKR04

Does Norman MCP support DATEV exports?

Yes. Norman MCP Server provides DATEV EXTF (Buchungsstapel) exports for German bookkeeping with SKR03 and SKR04. Ask your MCP-compatible AI assistant to prepare a DATEV export for a period, then download the file to share with your tax advisor (Steuerberater). Attached receipts can be included in a ZIP package.

Can I read an EXTF file without importing it into my books?

The read_datev_file tool reads EXTF/DTVF Buchungsstapel files, shows their header and booking rows, and filters by account, document date, text or amount. It requires an authenticated Norman company, but no DATEV connection or chart setup. Reading the file does not create transactions or Ledger postings.

Can I export the full GmbH/UG Ledger and check it before accountant handoff?

The Ledger export includes opening balances, manual entries, payroll, depreciation and closing postings. validate_ledger_datev_export checks the EXTF structure, source coverage and requested documents. Findings help prepare the handoff; they do not certify tax correctness or guarantee DATEV import acceptance.

Complete Ledger export, preflight and standalone file reading are implemented in this repository and require the matching Norman API endpoints. See DATEV tool details for limits and setup.

Example requests for these workflows:

• "Prepare a DATEV export for my Steuerberater for last quarter."
• "Read this EXTF file and show postings involving account 1800."
• "Check the full GmbH Ledger export before I give it to my accountant."

💬 Try asking

Once connected, talk to your books in plain language:

• "Prepare and file my UStVA for last month."
• "Show my Polish company's September JPK register and explain excluded operations."
• "Review my sp. z o.o. trial balance and prepared financial statement."
• "Send a €1,200 invoice to ACME for consulting."
• "What did I spend on software this quarter?"
• "Find tax deductions I might have missed."
• "Which invoices are overdue? Send reminders."

Interactive UI inside your AI assistant

Norman is more than a collection of background tools. In MCP Apps-compatible ChatGPT and Claude clients, Norman can render focused accounting workspaces directly inside the conversation. You can filter and inspect the underlying data, move between related views, and use Ask AI to continue the discussion with the current accounting context.

Try prompts such as:

• "Open my Norman Inbox and show what needs my attention."
• "Open my Document Review for the last 60 days."
• "Show my Reconciliation Cockpit and highlight missing documents or categories."
• "Open the Ledger Explorer and show the postings for account 1200."
• "Open my VAT return for July, generate the Finanzamt test preview, and explain anything I should review before submission."

The Norman API remains the source of truth. Opening or filtering a workspace does not change accounting data. Binding actions, including tax submission, remain separate MCP tool calls with their normal confirmation and permission checks. Clients without MCP Apps support receive the same underlying results as structured or text tool output.

Polish KPiR, full books, financial statements and JPK are available through the dedicated structured tools. The German Ledger Explorer and Finanzamt preview do not imply equivalent Polish interactive or submission workflows.

The SDK 2 HTTP transport limits MCP JSON request bodies to 4 MiB. Send larger documents through file_url or the upload page's file_ref, rather than inline base64. The separate multipart upload route keeps its own 50 MiB default, configurable with MCP_UPLOAD_MAX_SIZE.

🏢 Starting a company

Found a German GmbH or UG (haftungsbeschränkt) end-to-end — Norman collects the data, prepares the documents, and hands off to a notary:

• "I want to start a GmbH in Berlin — walk me through it."
• "Found a UG for me and two co-founders, split the shares 60/40."
• "Is 'Wunderbar Robotics' still free in the Handelsregister?"
• "Reword my business purpose so it's ready for the register."
• "Generate the Musterprotokoll and find me a notary who does online notarization."
• "What's left before my company is officially registered?"
• "Which Finanzamt is responsible for my company's address?"

Choosing GmbH/UG also sets your Norman account to the corporate SKR04 chart of accounts, so bookkeeping and taxes are ready from day one. The documents are drafts to prepare the notary appointment — not legal advice.

🚀 Get Started

Before connecting, create a free Norman account if you don't have one yet. Log in with your Norman credentials via OAuth — your password never touches the AI.

For a Polish business, use Polish signup. After connecting, confirm the selected company through company://current before inspecting or changing its books.

1. Go to Claude Connectors
2. Click Add
3. Find and connect: Norman Finance

MCP Apps-compatible Claude hosts can open Norman's interactive accounting workspaces directly in the conversation. Other Claude clients receive the same data as normal tool output.

Norman is available as a Claude Code plugin with built-in skills.

/plugin marketplace add norman-finance/norman-mcp-server
/plugin install norman-finance@norman-finance

Or install directly from GitHub:

claude /plugin install github:norman-finance/norman-mcp-server

1. Install it from the official ChatGPT Plugins Directory.

The plugin includes Norman's interactive accounting workspaces, including Document Review, Reconciliation, Ledger Explorer, and the explicit tax preview and submission flow.

Gemini CLI extension

gemini extensions install https://github.com/norman-finance/norman-mcp-server

Start Gemini CLI and authenticate the remote server when prompted, or run:

/mcp auth norman-finance

Gemini Spark custom app

Create a Spark, add a custom app, and use https://mcp.norman.finance/mcp as its MCP server URL. Availability depends on your Gemini account and region. See Google's custom app guide.

1. Open Account settings → Connectors
2. Click + Custom Connector and select Remote
3. Enter Norman Finance and https://mcp.norman.finance/mcp
4. Save the connector and complete Norman OAuth

Organization administrators can share the remote connector with their team.

Grok web

1. Go to Grok Connectors
2. Click New Connector → Custom
3. Enter https://mcp.norman.finance/mcp and complete Norman OAuth

Grok CLI

grok mcp add --transport http norman-finance https://mcp.norman.finance/mcp

Grok CLI also discovers this repository's .mcp.json automatically.

Option 1 — Remote with OAuth

Run in OpenClaw:

mcp add https://mcp.norman.finance/mcp

You'll be prompted to log in with your Norman account on first use.

Option 2 — Skills only

git clone https://github.com/norman-finance/norman-mcp-server.git
cp -r norman-mcp-server/skills/* ~/.openclaw/skills/
openclaw gateway restart

Option 3 — Local stdio

pip install norman-mcp-server

openclaw mcp add norman -- norman-mcp --transport stdio

Set your credentials as environment variables (NORMAN_EMAIL, NORMAN_PASSWORD) before starting the gateway.

1. Create an MCP OAuth2 API credential
2. Enable Dynamic Client Registration
3. Set Server URL: https://mcp.norman.finance/
4. Click Connect my account and log in with Norman
5. Add an MCP Client Tool node to your AI Agent workflow
6. Set the URL to https://mcp.norman.finance/mcp and select the credential

Add a remote HTTP MCP server with URL:

https://mcp.norman.finance/mcp

Skills

Ready-to-use skills compatible with Claude Code, OpenClaw, and the Agent Skills standard.

Claude Code  —  /plugin marketplace add norman-finance/norman-mcp-server

Claude Code (local)  —  claude --plugin-dir ./norman-mcp-server

OpenClaw  —  cp -r skills/* ~/.openclaw/skills/ && openclaw gateway restart

See the German VAT item workflow for item-level treatments, fixed documented EUR input VAT, refunds and manual VAT-only corrections. For Poland, see VAT codes and document currencies. Requires the corresponding API migrations and calculation updates.

Norman Inbox and MCP Events (development)

open_norman_inbox declares global/sidebar and thread entrypoints for hosts that support plugin extensions. MCP Apps hosts can render the same self-contained UI; other clients can call get_norman_inbox_data and get_norman_approval_data for structured results. Workflow questions use actual blocking state. Pending approval totals include all pages; tax reviews are a bounded list. Source failures are shown as unavailable. The Inbox also shows latest synced bank balances grouped by their original currency, overdue unpaid invoices, unattached invoice/receipt documents and unfinalized transactions with status UNVERIFIED. These task counts cover all history. Transaction totals cover the previous and current calendar months, with the date range displayed. Counts come from pagination totals, not the single record requested with each counter. Overdue invoices use Norman's stored overdue status; bank snapshots may lag the bank and are not profit. Task buttons delegate work to the conversation with the selected company and scope. The assistant can complete supported, evidence-backed document matching, categorization and finalization through existing tools, then report verified results and genuine blockers. Financial overview is analysis-only; invoice follow-ups prepare drafts. External messages, payments, tax filing and automation approvals require a separate decision. The iframe sends a chat request rather than calling write tools itself; clients without messaging show a copyable request. Button-generated messages use readable references to the Inbox selection. Internal company and record IDs stay in structured app context, which is acknowledged before sending. When that context is unavailable, the request asks the user to confirm the company and relevant record; copyable requests also omit IDs. Below the financial overview, You can also ask Norman shows three contextual tasks with the remaining suggestions under Explore more tasks. Their order stays stable for the selected company while the panel refreshes. Spending analysis, tax readiness and accountant handover checks are read-only; invoice creation is restricted to an unsent draft, and tax previews never authorize filing. The additive capabilities object contains ledger and taxPreview discovery hints. One company detail read enables Ledger suggestions only for SMEs with an SKR03/SKR04 chart. A preview suggestion requires an existing prepared Autopilot run with a report ID; a missing suggestion does not mean no tax reports exist. Unknown eligibility hides specialized suggestions while general tasks remain usable. Raw company details are omitted, and the host and API still enforce tool availability and permissions. The header shows the selected company's name, legal form and country. Its picker loads non-archived companies on demand through list_companies, then switches with and re-reads the Inbox. Switching clears old decisions, confirmation and chat context before loading the replacement. An ambiguous timeout keeps actions unavailable until the requested company is verified; the switch is never automatically retried. The additive profile reuses the existing company lookup and excludes tax IDs, bank details and members. On mobile, the Inbox has a bounded inner scroll area, uses host safe-area insets, and condenses empty states and explanatory text. Standard host context controls theme and dimensions, with legacy OpenAI globals and OS theme fallbacks. Sidebar icons include explicit light and dark variants. Unbounded inline hosts retain natural height; previously cached Inbox resource URIs remain available. The review card uses existing approve/dismiss/undo tools and refreshes actual results. Approval requires a checkbox and re-reads current values and planned actions immediately before executing. A changed review requires confirmation again. The backend remains responsible for atomic execution and permissions. Non-transaction approvals whose current target is unavailable can be discussed or dismissed; they cannot be approved from this card.

The visible Inbox refreshes through get_norman_inbox_data 30 seconds after a completed read and backs off to 60, 120 and at most 300 seconds while nothing on screen changes; any interaction or change resets it to 30. Focus or becoming visible refreshes only once half the current interval has passed. It pauses while hidden/offscreen, during actions, on teardown, and after an expired session until the user acts. It keeps the selected page and typed workflow answer (a draft is bound to its question; if the question changes, sending needs confirmation); an unchanged approval keeps explicit consent, while changed current values or planned actions clear it. This uses the portable Apps tools/call bridge: iframe support for SDK 2 resource subscriptions is not assumed.

Hosted SDK 2 clients can separately opt into resource invalidations by setting NORMAN_MCP_INBOX_LIVE=1 on a single-process MCP deployment using the streamable-http transport (SSE starts one lifespan per connection, so the flag is ignored there with a warning). Credential-only stdio does not enable this feature. Existing tools and legacy refresh continue working when the setting is absent.

1. Call watch_norman_inbox with an approval page (default 1). It returns an opaque resourceUri, expiresAt (Unix seconds), and observation interval.
2. Open SDK 2 subscriptions/listen for that exact URI. After acknowledgment, call resources/read for the current snapshot; refetch on each notifications/resources/updated. Events contain only the opaque URI.
3. Reopen the watch after expiry, reconnect, token refresh, restart, or an attempted switch_company. Watches last at most five minutes and never outlive their MCP bearer token. There is no replay; always refetch on reconnect.

Read and listen both check the exact OAuth grant, client and selected company. Observers resolve only that grant's current Norman token and pin its company. An expired Norman token (one hour) is refreshed through that grant; a 401 that survives the refresh, or a 403, closes the watch. Local grant revocation, company changes and expiry end its stream within one second. The observer reads only while a stream is connected, with 30 seconds between observation cycles. Each watch observes one approval page, workflow state, bounded tax reviews, discovery capabilities and the Inbox overview; it is not a complete company event log and may miss intermediate changes. Financial snapshots are never cached in the change bus. There are at most 128 leases/streams, four leases and four open streams per OAuth grant, four concurrent snapshot reads (normally ten API requests per snapshot) and two per grant. The grant-pinned reader permits only GET requests. Tokens refreshed from one authorization share its grant, so refreshing does not raise these limits.

Leases and the SDK subscription bus are in memory. Use one process/replica; multiple replicas require shared lease state, OAuth state and a distributed subscription bus before this feature can be enabled reliably. This read-only feed is separate from the durable webhook events below.

The opt-in workflow.attention_required event implements the draft MCP Events contract on SDK 2 / protocol 2026-07-28. It watches one explicitly selected company and workflow through the Norman API and sends signed webhooks when the active run becomes blocked. It does not advance workflows, send invoice reminders or file taxes. Current delivery waits 30 seconds between source observation cycles; it does not yet consume a backend event stream and can miss transitions between observations.

To enable events on a hosted single-worker Streamable HTTP deployment, set:

• NORMAN_MCP_EVENTS_DB: an absolute SQLite path on a persistent private volume.
• NORMAN_MCP_EVENTS_KEY: a Fernet encryption key from your secret manager. Keep the same key across restarts; changing it makes stored subscriptions unreadable.

Start with norman-mcp --transport streamable-http --public-url https://your-host. Both settings are required. Without them, events are not advertised. SQLite state contains encrypted authentication references, callback URLs, signing keys and pending payloads. Persist the existing MCP_OAUTH_STATE_FILE on a private volume as well: delivery after restart needs valid OAuth tokens and Norman token mappings. The worker reads each run with the subscriber's own grant and company; an expired Norman access token (one hour) is refreshed through that grant, and a grant that cannot be refreshed suspends delivery until the client refreshes the subscription. Nothing falls back to other credentials. Multiple worker processes/replicas require coordinated OAuth storage and a distributed delivery lease before enabling events.

Subscriptions use events/list, events/subscribe and events/unsubscribe, with arguments { "company_id": "UUID", "run_id": "UUID" } and webhook delivery { "mode": "webhook", "url": "https://public-callback", "secret": "whsec_…" }. The receiver must echo the signed verification challenge. Subscription lifetime is capped at one hour and authentication expiry; renew before refreshBefore. Secret rotation accepts the previous signing key for five minutes. Each retry keeps the same eventId; receivers should deduplicate by it. Permanent callback failures stop retries until the subscription is renewed, and HTTP 410 removes the subscription. Callback addresses are validated and DNS-pinned to public HTTPS endpoints; redirects are not followed. Each callback, verification included, has 15 seconds in total and runs in a small dedicated pool.

Host support, plugin submission and production activation need separate verification. Local protocol and browser fixtures do not establish ChatGPT catalog availability or a successful production OAuth/webhook connection.

DATEV files and complete Ledger exports

For German companies, trigger_datev_export defaults to the complete Ledger for GmbH/UG (isSme), including opening, manual, payroll, depreciation and closing entries. Other German companies retain the finalized-transactions export. Use source="transactions" only for an explicitly requested transactions-only export. A Ledger failure never falls back to that narrower export. The API checks the journal before returning an expiring download link and includes its validation findings in the response. With include_documents=true, the ZIP contains the journal, account reports and available linked documents; unreadable attached documents block the package.

• validate_ledger_datev_export: preview structure, source coverage and documents for a period without saving company settings, creating a download or sending it.
• read_datev_file: inspect an uploaded EXTF/DTVF Buchungsstapel without importing it. Obtain a file_ref through request_file_upload or POST /files/upload, then filter by account, document date, text or minimum amount. Reuse that reference for subsequent pages (up to 100 rows/page) until its normal upload expiry. No DATEV connection or chart setup is needed; an authenticated Norman company is required. CSV/TXT/EXTF uploads are limited to 20 MB / 100,000 rows; extract the booking CSV from a ZIP before uploading.

The reader preserves tax keys and Generalumkehr markers. Its totals are source-row amounts grouped by currency, not tax-expanded account balances or open items. Structural checks do not certify tax correctness or acceptance by DATEV. Nothing in these tools emails an accountant or pushes an export to DATEV.

The API release providing Ledger responseFormat/validateOnly and /companies/{id}/accounting/datev/read/ must be deployed before this MCP release.