{
  "markdown": "# Précis Finance MCP\n\n[![License: Elastic 2.0](https://img.shields.io/badge/license-Elastic%202.0-0D9488)](LICENSE)\n[![MCP](https://img.shields.io/badge/MCP-server-0D9488)](https://modelcontextprotocol.io)\n[![CI](https://github.com/precis-finance/precis-finance-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/precis-finance/precis-finance-mcp/actions/workflows/ci.yml)\n[![Docs](https://img.shields.io/badge/docs-precis.finance-0D9488)](https://docs.precis.finance/)\n\nA read-only, self-hosted [MCP](https://modelcontextprotocol.io) server for FP&A\nand management reporting: governed metrics, financial statements, and row-level\ndrill-down over a SQL semantic layer — **your own warehouse, not market data.**\nThe open core of **Précis**, the agentic Finance Intelligence Platform.\n\nYou describe your business metrics once — KPIs, hierarchies, and\nfinancial-statement layouts in a YAML catalogue over a semantic layer of plain\nSQL views, versioned in git — and any MCP-capable client gets consistent,\ndefensible numbers. The semantic views are plain SQL in your ClickHouse, so your\nexisting BI tools can query the same views directly. This repository is complete and\nself-hostable — the metric engine, semantic layer and catalogue, ingestion,\nidentity, and the MCP transport — and depends on nothing outside it.\n\n## Use this if\n\n- You run or support a finance function and want AI clients — Claude, ChatGPT,\n  or any MCP-capable client — answering questions and pulling management\n  reporting from your own numbers.\n- You need **governed** metrics — one agreed definition of gross margin,\n  utilisation, or revenue by business unit — not an agent querying raw rows in\n  the general ledger or inventing its own definitions.\n- You want it **self-hosted**, on infrastructure you already operate and under a\n  security model you control — not another cloud contract.\n- You need every answer traceable: **read-only by construction**, no figure\n  generated by the model, every number aggregated from semantic views you can\n  read.\n\n## Requirements\n\n- **Docker** — Engine + Compose v2. Everything runs in containers; there is\n  nothing else to install.\n- **No warehouse to provision** — the stack bundles ClickHouse (the engine's\n  analytical store) and PostgreSQL (platform state — users, sessions, audit). A\n  local trial runs with nothing else and loads a sample finance model.\n- **Already run ClickHouse?** — optionally point the engine at your own instance\n  instead of the bundled one; see\n  [data modes](docs/deployment/clickhouse-data-modes.md).\n- **An MCP-capable client** — Claude (claude.ai and Desktop connectors, against\n  a deployed instance), Claude Code, ChatGPT, or any MCP client.\n- **Optional Excel access** — the multi-user image also hosts the Précis Excel\n  add-in at `/excel`; enable its OAuth client when you want live read-only\n  workbook functions.\n\n## What Précis Finance MCP looks like\n\n![Claude, connected to Précis over MCP, rendering a governed P&L with comparatives and then drilling Revenue down to cost-centre level — sample data](docs/assets/precis-mcp-demo.gif)\n\nEvery figure aggregates from the semantic views — account, cost centre,\nperiod, scenario — and the measures generic metric layers can't express\n(a utilisation denominator averaged across periods, re-aggregated by quarter\nor business unit, with subtotals in the layout) are first-class catalogue\ndefinitions.\n\n## Quickstart — single-user local trial\n\n```sh\nexport MCP_DEV_KEY=$(openssl rand -hex 32)\ndocker compose -f deploy/docker-compose.local.yml up -d --build\ndocker compose -f deploy/docker-compose.local.yml exec precis-mcp \\\n  python -m precis_mcp.sample_data   # populate the demo model\n```\n\nOne stack — the server plus a bundled ClickHouse and Postgres — a shared dev\nkey, bound to `127.0.0.1`. Point any MCP client at `http://127.0.0.1:8768/mcp`\nwith the dev key as bearer token. For example, with Claude Code:\n\n```sh\nclaude mcp add --transport http precis http://127.0.0.1:8768/mcp \\\n  --header \"Authorization: Bearer $MCP_DEV_KEY\"\n```\n\nThen ask a finance-specific question to prove this is not a generic SQL MCP:\n*\"Show the P&L for FY2025 with comparatives.\"* · *\"Drill revenue down by cost\ncentre.\"* · *\"Show utilisation by month for the Digital Transformation team.\"*\n\nFull walkthrough, including the demo data and bringing your own model:\n[docs/getting-started/quickstart.md](docs/getting-started/quickstart.md).\n\nRather do this on a call? We pair with early adopters to stand Précis Finance MCP up\nagainst their own warehouse — [precis.finance](https://precis.finance) or\n[hello@precis.finance](mailto:hello@precis.finance).\n\n## Multi-user deployment\n\n`deploy/docker-compose.yml` runs the multi-user stack — the open server,\nPostgreSQL, ClickHouse, and OAuth 2.1 + PKCE sign-in. Deployment is modular\nalong independent axes:\n\n- **Data** — bundled ClickHouse (empty or with sample data) or your own:\n  [docs/deployment/clickhouse-data-modes.md](docs/deployment/clickhouse-data-modes.md)\n- **Identity** — local dev key, the bundled Keycloak (optionally federated to\n  your IdP), or a direct external OIDC provider (Auth0 / Okta / Entra / Ping):\n  [docs/deployment/oauth-keycloak.md](docs/deployment/oauth-keycloak.md),\n  [docs/deployment/external-idp-recipes.md](docs/deployment/external-idp-recipes.md)\n- **Ingress** — the bundled Caddy proxy (`bundled-proxy` profile, on by\n  default) terminates TLS with automatic Let's Encrypt certificates from\n  nothing but `PRECIS_DOMAIN`. The app itself is proxy-agnostic: drop the\n  profile to front it with an ingress you already operate (reference nginx\n  vhost in `deploy/nginx/`, host helper `scripts/install-precis-mcp.sh --nginx`)\n- **Backups** — additive `backup` compose profile: scheduled bundles\n  (Postgres dump + ClickHouse backup + instance config) to a local volume or\n  S3, with restore and drill commands:\n  [docs/operations/backups.md](docs/operations/backups.md)\n- **Excel add-in** — optional hosted workbook functions served from the same\n  instance at `/excel`; enable with the bundled Keycloak client or a public\n  client in your external IdP:\n  [docs/excel/](docs/excel/index.md)\n\n`scripts/deploy-mcp.sh --data-mode ... --auth-mode ...` is the friendly front\ndoor over the Compose profiles. Every knob is an environment variable:\n[docs/configuration/environment-variables.md](docs/configuration/environment-variables.md).\n\n## Configure your data model\n\nYour model lives in an `instance/` directory — metric catalogue, semantic SQL\nviews, ingestion bindings — and the bundled demo instance shows the shape.\nStart at [docs/configuration/catalogue-and-semantic.md](docs/configuration/catalogue-and-semantic.md),\nthen [docs/configuration/ingestion.md](docs/configuration/ingestion.md) and\n[docs/operations/onboarding-ingestion.md](docs/operations/onboarding-ingestion.md)\nto load your data. The developer guide for adding server tools is\n[docs/development/adding-read-tools.md](docs/development/adding-read-tools.md).\n\n## Security and read-only posture\n\nStart with the mechanisms, not the promise.\n\n- **Read-only by construction** — the server retrieves; it never writes to or\n  changes your source. There is no write path back.\n- **No figure is generated by the model** — tools return numbers aggregated from\n  source dimensions (account, cost centre, period, scenario), or report that the\n  data isn't there. The client composes the question and narrates the answer; it\n  never invents a figure.\n- **Traceable to source** — every number traces from response → semantic view →\n  warehouse. The semantic views are plain SQL you can read; the catalogue is\n  versioned in git.\n- **Your own warehouse, not market data** — it runs in your environment, against\n  your warehouse, under your own access controls.\n- **Identity** — a local dev key, the bundled Keycloak (optionally federated to\n  your IdP), or a direct external OIDC provider (Auth0 / Okta / Entra / Ping).\n- **Operator responsibility** — Précis Finance MCP is designed to expose governed read\n  operations; you still deploy and operate it under your own security model.\n  Disclosure policy: [SECURITY.md](SECURITY.md).\n\n## Documentation\n\nFull documentation: [docs.precis.finance](https://docs.precis.finance/).\n\n| Area | Start here |\n|---|---|\n| Getting started | [quickstart](docs/getting-started/quickstart.md) |\n| Deployment | [ClickHouse data modes](docs/deployment/clickhouse-data-modes.md) · [OAuth / Keycloak](docs/deployment/oauth-keycloak.md) · [external IdP recipes](docs/deployment/external-idp-recipes.md) |\n| Excel | [Précis for Excel](docs/excel/index.md) · [function reference](docs/excel/functions.md) |\n| Configuration | [catalogue & semantic layer](docs/configuration/catalogue-and-semantic.md) · [ingestion](docs/configuration/ingestion.md) · [environment variables](docs/configuration/environment-variables.md) |\n| Operations | [onboarding & ingestion](docs/operations/onboarding-ingestion.md) · [backups](docs/operations/backups.md) |\n| Development | [adding read tools](docs/development/adding-read-tools.md) |\n| Security | [SECURITY.md](SECURITY.md) |\n\n## Précis Finance MCP vs Précis\n\nThe deployment and data model you build here are the foundation the full\n[**Précis**](https://precis.finance) platform runs on. Précis is currently\npre-General Availability and adds a licensed agentic workspace over this same\nengine and data model. Moving from the open core to Précis is workflow\nconfiguration and adoption — not a second data-integration project. Précis\nprepares; the finance professional decides.\n\n### What ships — and what doesn't\n\n**Ships in Précis Finance MCP (Elastic License 2.0):** the MCP server and transport ·\nmetric engine · financial-statement layouts · semantic SQL view pattern · YAML\nmetric catalogue · sample finance model · ingestion path · hosted read-only\nExcel add-in · ClickHouse analytical store · PostgreSQL platform state · local\ndev-key mode · multi-user OAuth 2.1 mode · Docker Compose deployment · backup &\nrestore profile · configuration and deployment docs.\n\n**Lives in Précis, not in this repo:** the workspace UI · the conversational\nagent · plan write-back · scenario commit workflows · scheduled Dispatch\nbriefings · report / management-pack workflow · Excel write-back / round-trip ·\ncommercial support (unless separately agreed).\n\n**Talk about Précis** — the full platform and design-partner programme:\n[precis.finance](https://precis.finance) or\n[hello@precis.finance](mailto:hello@precis.finance).\n\n## Support and services\n\nPrécis Finance MCP is built to be self-serve, and the [documentation](https://docs.precis.finance/) aims to be\nenough. If you'd like help beyond it — configuring your data model, a guided\ndeployment, ongoing support, or a demo environment to evaluate against realistic\ndata — book a setup session at [precis.finance](https://precis.finance) or write\nto [hello@precis.finance](mailto:hello@precis.finance). The same address reaches\nthe team behind the full Précis platform.\n\n## Contributing\n\nThis repository is a one-way mirror of the Précis monorepo: `main` advances\nby sync commits, and pull requests are applied internally with your authorship\nand DCO sign-off preserved, then published in the next sync. See\n[CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\n[Elastic License 2.0](LICENSE) — source-available. Free to use, modify,\nself-host (including commercially), and redistribute; you may not offer it to\nthird parties as a hosted or managed service.\n",
  "bytes": 11478,
  "sha": "a5001818ab9c0d6a690775b5b999bcea0fcac51791551a65ca297f188d9b2cd8",
  "repo_slug": "precis-finance/precis-finance-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_precis_finance_precis_finance__4487144c/readme"
}