precis-mcp

precis-mcp

A read-only, self-hosted MCP server for FP&Aand management reporting: governed metrics, financial statements, and row-leveldrill-down over a SQL semantic layer — your own warehouse, not market data.The open core of Précis, the agentic Finance Intelligence Platform.

You describe your business metrics once — KPIs, hierarchies, andfinancial-statement layouts in a YAML catalogue over a semantic layer of plainSQL views, versioned in git — and any MCP-capable client gets consistent,defensible numbers. The semantic views are plain SQL in your ClickHouse, so yourexisting BI tools can query the same views directly. This repository is complete andself-hostable — the metric engine, semantic layer and catalogue, ingestion,identity, and the MCP transport — and depends on nothing outside it.

Use this if

• You run or support a finance function and want AI clients — Claude, ChatGPT,or any MCP-capable client — answering questions and pulling managementreporting from your own numbers.
• You need governed metrics — one agreed definition of gross margin,utilisation, or revenue by business unit — not an agent querying raw rows inthe general ledger or inventing its own definitions.
• You want it self-hosted, on infrastructure you already operate and under asecurity model you control — not another cloud contract.
• You need every answer traceable: read-only by construction, no figuregenerated by the model, every number aggregated from semantic views you canread.

Requirements

• Docker — Engine + Compose v2. Everything runs in containers; there isnothing else to install.
• No warehouse to provision — the stack bundles ClickHouse (the engine'sanalytical store) and PostgreSQL (platform state — users, sessions, audit). Alocal trial runs with nothing else and loads a sample finance model.
• Already run ClickHouse? — optionally point the engine at your own instanceinstead of the bundled one; seedata modes.
• An MCP-capable client — Claude (claude.ai and Desktop connectors, againsta deployed instance), Claude Code, ChatGPT, or any MCP client.
• Optional Excel access — the multi-user image also hosts the Précis Exceladd-in at /excel; enable its OAuth client when you want live read-onlyworkbook functions.

What precis-mcp looks like

Every figure aggregates from the semantic views — account, cost centre,period, scenario — and the measures generic metric layers can't express(a utilisation denominator averaged across periods, re-aggregated by quarteror business unit, with subtotals in the layout) are first-class cataloguedefinitions.

Quickstart — single-user local trial

export MCP_DEV_KEY=$(openssl rand -hex 32)
docker compose -f deploy/docker-compose.local.yml up -d --build
docker compose -f deploy/docker-compose.local.yml exec precis-mcp \
  python -m precis_mcp.sample_data   # populate the demo model

One stack — the server plus a bundled ClickHouse and Postgres — a shared devkey, bound to 127.0.0.1. Point any MCP client at http://127.0.0.1:8768/mcpwith the dev key as bearer token. For example, with Claude Code:

claude mcp add --transport http precis http://127.0.0.1:8768/mcp \
  --header "Authorization: Bearer $MCP_DEV_KEY"

Then ask a finance-specific question to prove this is not a generic SQL MCP:"Show the P&L for FY2025 with comparatives." · "Drill revenue down by costcentre." · "Show utilisation by month for the Digital Transformation team."

Full walkthrough, including the demo data and bringing your own model:docs/getting-started/quickstart.md.

Rather do this on a call? We pair with early adopters to stand precis-mcp upagainst their own warehouse — precis.finance or[email protected].

Multi-user deployment

deploy/docker-compose.yml runs the multi-user stack — the open server,PostgreSQL, ClickHouse, and OAuth 2.1 + PKCE sign-in. Deployment is modularalong independent axes:

• Data — bundled ClickHouse (empty or with sample data) or your own:docs/deployment/clickhouse-data-modes.md
• Identity — local dev key, the bundled Keycloak (optionally federated toyour IdP), or a direct external OIDC provider (Auth0 / Okta / Entra / Ping):docs/deployment/oauth-keycloak.md,docs/deployment/external-idp-recipes.md
• Ingress — the bundled Caddy proxy (bundled-proxy profile, on bydefault) terminates TLS with automatic Let's Encrypt certificates fromnothing but PRECIS_DOMAIN. The app itself is proxy-agnostic: drop theprofile to front it with an ingress you already operate (reference nginxvhost in deploy/nginx/, host helper scripts/install-precis-mcp.sh --nginx)
• Backups — additive backup compose profile: scheduled bundles(Postgres dump + ClickHouse backup + instance config) to a local volume orS3, with restore and drill commands:docs/operations/backups.md
• Excel add-in — optional hosted workbook functions served from the sameinstance at /excel; enable with the bundled Keycloak client or a publicclient in your external IdP:docs/excel/

scripts/deploy-mcp.sh --data-mode ... --auth-mode ... is the friendly frontdoor over the Compose profiles. Every knob is an environment variable:docs/configuration/environment-variables.md.

Configure your data model

Your model lives in an instance/ directory — metric catalogue, semantic SQLviews, ingestion bindings — and the bundled demo instance shows the shape.Start at docs/configuration/catalogue-and-semantic.md,then docs/configuration/ingestion.md anddocs/operations/onboarding-ingestion.mdto load your data. The developer guide for adding server tools isdocs/development/adding-read-tools.md.

Security and read-only posture

Start with the mechanisms, not the promise.

• Read-only by construction — the server retrieves; it never writes to orchanges your source. There is no write path back.
• No figure is generated by the model — tools return numbers aggregated fromsource dimensions (account, cost centre, period, scenario), or report that thedata isn't there. The client composes the question and narrates the answer; itnever invents a figure.
• Traceable to source — every number traces from response → semantic view →warehouse. The semantic views are plain SQL you can read; the catalogue isversioned in git.
• Your own warehouse, not market data — it runs in your environment, againstyour warehouse, under your own access controls.
• Identity — a local dev key, the bundled Keycloak (optionally federated toyour IdP), or a direct external OIDC provider (Auth0 / Okta / Entra / Ping).
• Operator responsibility — precis-mcp is designed to expose governed readoperations; you still deploy and operate it under your own security model.Disclosure policy: SECURITY.md.

Documentation

Full documentation: docs.precis.finance.

precis-mcp vs Précis

The deployment and data model you build here are the foundation the fullPrécis platform runs on. Précis is currentlypre-General Availability and adds a licensed agentic workspace over this sameengine and data model. Moving from the open core to Précis is workflowconfiguration and adoption — not a second data-integration project. Précisprepares; the finance professional decides.

What ships — and what doesn't

Ships in precis-mcp (Elastic License 2.0): the MCP server and transport ·metric engine · financial-statement layouts · semantic SQL view pattern · YAMLmetric catalogue · sample finance model · ingestion path · hosted read-onlyExcel add-in · ClickHouse analytical store · PostgreSQL platform state · localdev-key mode · multi-user OAuth 2.1 mode · Docker Compose deployment · backup &restore profile · configuration and deployment docs.

Lives in Précis, not in this repo: the workspace UI · the conversationalagent · plan write-back · scenario commit workflows · scheduled Dispatchbriefings · report / management-pack workflow · Excel write-back / round-trip ·commercial support (unless separately agreed).

Talk about Précis — the full platform and design-partner programme:precis.finance or[email protected].

Support and services

precis-mcp is built to be self-serve, and the documentation aims to beenough. If you'd like help beyond it — configuring your data model, a guideddeployment, ongoing support, or a demo environment to evaluate against realisticdata — book a setup session at precis.finance or writeto [email protected]. The same address reachesthe team behind the full Précis platform.

Contributing

This repository is a one-way mirror of the Précis monorepo: main advancesby sync commits, and pull requests are applied internally with your authorshipand DCO sign-off preserved, then published in the next sync. SeeCONTRIBUTING.md.

License

Elastic License 2.0 — source-available. Free to use, modify,self-host (including commercially), and redistribute; you may not offer it tothird parties as a hosted or managed service.