Précis Finance MCP

Précis Finance MCP

一款只读、可自托管的 MCP 服务，面向 FP&A 和管理报告：通过 SQL 语义层提供受治理的指标、财务报表、行级下钻、图表和快照文件导出——使用你自己的数据仓库，而不是市场数据。 Précis 智能 Finance Intelligence Platform 的开源核心。

你只需定义一次业务指标——在纯 SQL 视图构成的语义层之上，用 YAML 目录描述 KPI、层级和财务报表布局，并通过 git 进行版本管理——任何兼容 MCP 的客户端都能获得一致且有依据的数据。语义视图是 ClickHouse 中的纯 SQL，因此现有 BI 工具也能直接查询相同的视图。本代码库包含完整且可自托管的系统——指标引擎、语义层和目录、数据摄取、身份管理以及 MCP 传输——不依赖任何外部服务。

适用场景

• 你运营或支持财务职能，希望 AI 客户端——Claude、ChatGPT 或任何兼容 MCP 的客户端——根据自有数据回答问题并生成管理报告。
• 你需要受治理的指标——例如毛利率、利用率或按业务部门划分的收入都采用统一认可的定义——而不是让 Agent 查询总账中的原始行，或自行编造定义。
• 你希望在自己运营的基础设施上自托管，并采用由你掌控的安全模型，而不是再签一份云服务合同。
• 你需要每个答案都可追溯：系统从设计上只读，模型不会生成任何数据，每个数字都由你可查看的语义视图聚合而来。

要求

• Docker——Engine + Compose v2。所有内容都在容器中运行；无需安装其他任何内容。
• 无需预配数据仓库——该栈内置 ClickHouse（引擎的分析存储）、PostgreSQL（平台和工件状态）以及 Valkey（临时快照）。本地试用无需其他依赖，并会加载示例财务模型。
• 已经在运行 ClickHouse？——你可以选择让引擎连接自己的实例，而不是使用内置实例；请参阅 数据模式。
• 兼容 MCP 的客户端——Claude（通过 Claude.ai 和 Desktop 连接器连接已部署的实例）、Claude Code、ChatGPT 或任何 MCP 客户端。
• 可选的 Excel 访问——多用户镜像还会在 /excel 托管 Précis Excel 加载项；如需使用实时只读工作簿函数，请启用其 OAuth 客户端。

Précis Finance MCP 的效果

每个数字都基于语义视图聚合——科目、成本中心、期间、情景——而通用指标层无法表达的度量（例如按期间平均利用率分母，再按季度或业务部门重新聚合，并在布局中加入小计）也都可以作为一等目录定义使用。

试用公开演示

将远程 MCP 客户端连接到 **https://mcp.precis.finance/mcp**，即可探索 Précis Finance MCP，无需安装任何内容或创建账户。共享服务通过合成财务数据集提供只读工具；其中不包含您的财务数据。无需 API 密钥或登录。

对于 Claude Code：

claude mcp add --transport http precis-demo https://mcp.precis.finance/mcp

然后询问 precis_orientation 演示支持哪些功能，或请求查看包含对比数据的损益表。有关其他 MCP 客户端以及此共享实例的限制，请参阅公开演示连接指南。

快速入门 — 单用户本地试用

export MCP_DEV_KEY=$(openssl rand -hex 32)
export ARTIFACT_SIGNING_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

一个技术栈——服务以及 ClickHouse、Postgres 和 Valkey——一个共享开发密钥，绑定到 127.0.0.1。将任意 MCP 客户端指向 http://127.0.0.1:8768/mcp，并将开发密钥用作 bearer token。例如，使用 Claude Code：

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

然后提出一个特定于财务的问题，以证明这不是通用 SQL MCP： “显示 FY2025 的损益表，并附上对比数据。” · “按成本中心细分收入。” · “显示数字化转型团队按月的利用率。”

完整演练（包括演示数据和接入自有模型）请参阅： docs/getting-started/quickstart.md。

想在通话中完成这些操作？我们会与早期采用者合作，将 Précis Finance MCP 接入他们自己的数据仓库 —— precis.finance 或 [email protected]。

多用户部署

deploy/docker-compose.yml 运行多用户技术栈——开源服务、 PostgreSQL、ClickHouse、Valkey、制品存储，以及 OAuth 2.1 + PKCE 登录。部署可沿相互独立的维度进行模块化配置：

• 数据 — 捆绑的 ClickHouse（空实例或包含示例数据）或您自己的数据： docs/deployment/clickhouse-data-modes.md
• 身份 — 本地开发密钥、捆绑的 Keycloak（可选与您的 IdP 联合），或直接使用外部 OIDC 提供商（Auth0 / Okta / Entra / Ping）： docs/deployment/oauth-keycloak.md， docs/deployment/external-idp-recipes.md
• 入口 — 捆绑的 Caddy 代理（bundled-proxy 配置，默认启用）仅需设置 PRECIS_DOMAIN，即可自动获取 Let's Encrypt 证书并终止 TLS。应用本身与代理无关：移除该配置，即可使用您已有的入口代理（deploy/nginx/ 中提供 nginx 虚拟主机参考配置；主机辅助脚本为 scripts/install-precis-mcp.sh --nginx）
• 备份 — 附加的 backup Compose 配置：定时将打包内容（Postgres 转储 + ClickHouse 备份 + 实例配置）保存到本地卷或 S3，并提供恢复和演练命令： docs/operations/backups.md
• Excel 加载项 — 可选的托管工作簿函数，由同一实例通过 /excel 提供；可使用捆绑的 Keycloak 客户端或外部 IdP 中的公共客户端启用： docs/excel/

scripts/deploy-mcp.sh --data-mode ... --auth-mode ... 是便捷入口，可配置 Compose 配置。所有配置项均为环境变量： docs/configuration/environment-variables.md。

配置数据模型

您的模型位于 instance/ 目录中——包括指标目录、语义 SQL 视图和数据摄取绑定——捆绑的演示实例展示了其结构。请先阅读 docs/configuration/catalogue-and-semantic.md， 然后阅读 docs/configuration/ingestion.md 和 docs/operations/onboarding-ingestion.md 以加载数据。有关添加服务工具的开发者指南，请参阅 docs/development/adding-read-tools.md。

安全性与只读特性

先看机制，而不是承诺。

• 从设计上只读 — 服务只检索数据，绝不会写入或更改你的数据源。没有回写路径。
• 模型不会生成任何数字 — 工具会返回根据源数据维度（账户、成本中心、期间、场景）汇总的数字，或者说明数据不存在。客户端负责组织问题并讲述答案，绝不会编造数字。
• 可追溯至数据源 — 每个数字都可从响应 → 语义视图 → 数据仓库追溯。语义视图是可直接阅读的 SQL；目录在 git 中进行版本管理。
• 使用你自己的数据仓库，而非市场数据 — 它在你的环境中运行，针对你的数据仓库，并遵循你自己的访问控制。
• 身份验证 — 可使用本地开发密钥、随附的 Keycloak（可选择联合到你的 IdP），或直接使用外部 OIDC 提供商（Auth0 / Okta / Entra / Ping）。
• 运营者责任 — Précis Finance MCP 旨在提供受治理的只读操作；你仍需根据自己的安全模型部署和运营它。信息披露政策：SECURITY.md。

文档

完整文档：docs.precis.finance。

领域	从这里开始
入门	快速入门
部署	ClickHouse 数据模式 · OAuth / Keycloak · 外部 IdP 配置指南
Excel	Précis for Excel · 函数参考
配置	目录与语义层 · 数据摄取 · 环境变量
运维	入驻与数据摄取 · 备份
开发	添加只读工具
安全	SECURITY.md

Précis Finance MCP 与 Précis 的区别

你在此构建的部署和数据模型，是完整的 Précis 平台运行的基础。Précis 目前尚未正式发布，并在同一引擎和数据模型之上增加了需要授权的 Agent 工作区。从开源核心迁移到 Précis，需要进行工作流配置和采用，而不是开展第二个数据集成项目。Précis 负责准备；财务专业人士负责决策。

包含的内容 — 不包含的内容

Précis Finance MCP 中包含（Elastic License 2.0）： MCP 服务和传输 · 指标引擎 · 财务报表布局 · 语义 SQL 视图模式 · YAML 指标目录 · 示例财务模型 · 数据摄取路径 · 托管式只读 Excel 加载项 · ClickHouse 分析型存储 · PostgreSQL 平台状态 · 本地开发密钥模式 · 多用户 OAuth 2.1 模式 · Docker Compose 部署 · 备份与恢复配置 · 配置和部署文档。

属于 Précis，不在此仓库中： 工作区 UI · 对话式 Agent · 计划回写 · 场景提交工作流 · 定时 Dispatch 简报 · 报告 / 管理报告包工作流 · Excel 回写 / 往返 · 商业支持（除非另行约定）。

了解 Précis — 完整平台和设计合作伙伴计划： precis.finance 或 [email protected]。

支持与服务

Précis Finance MCP 专为自助使用而构建，文档旨在满足您的需求。如果您希望获得文档之外的帮助——例如配置数据模型、获得部署指导、持续支持，或使用真实数据评估的演示环境——请在 precis.finance 预约设置会议，或发送邮件至 [email protected]。同一邮箱也能联系到完整 Précis 平台背后的团队。

贡献

此仓库是 Précis 单体仓库的单向镜像：main 通过同步提交不断更新，拉取请求会在内部应用，并保留您的作者身份和 DCO 签署信息，然后在下一次同步时发布。请参阅 CONTRIBUTING.md。

许可证

Elastic License 2.0 — 源码可用。您可以免费使用、修改、可自托管（包括商业用途）并重新分发；但不得将其作为托管或管理服务提供给第三方。