convez.ai
MCP ServerFinanceiroIntermediário
arikanatakan

finvariant-mcp

arikanatakan/finvariant-mcp

Auditoria determinística de demonstrações financeiras para agentes IA

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que expõe verificações determinísticas de integridade de demonstrações financeiras para agentes de IA. Valida se o balanço patrimonial fecha, se o fluxo de caixa se articula, se os subtotais batem e se as três demonstrações estão alinhadas.

Instalação

$npx convez-ai arikanatakan/finvariant-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
4
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Validar demonstrações financeiras geradas por agentes IA
  • Verificar integridade de balanços patrimoniais e fluxos de caixa
  • Auditar articulation entre income statement, balance sheet e cash flow

Veredito

Ferramenta essencial para pipelines que geram ou processam demonstrações financeiras, garantindo integridade contábil de forma determinística. Bem documentada e pronta para produção com testes CI/CD.

README

A tradução para o português deste README ainda está na fila.

finvariant-mcp

CI PyPI License: MIT

An MCP server that exposes finvariant, the deterministic financial-statement integrity checker for Python, as a tool for AI agents: hand it income statement, balance sheet and cash flow data and it verifies that the balance sheet balances, the cash flow ties to the balance sheet, subtotals foot, and the three statements articulate.

Agents asked to build, read or summarise financial statements tend to produce the numbers themselves: a balance sheet that does not balance, a cash flow that does not tie, a retained-earnings figure that does not roll forward. Generated financial statements fail silently. The check belongs in a deterministic, versioned, validated library that the agent calls; the agent chooses what to verify and explains the verdict.

finvariant-mcp architecture: an AI agent calls the server's check_statements and describe_schema tools, which route to the validated finvariant core and return a structured audit report (verdict, findings, provenance)

Tools

ToolPurpose
check_statementsVerify statements against the accounting invariants; return a verdict, the failing checks with expected vs actual, counts, provenance and a plain-language summary.
describe_schemaThe canonical field names by statement, the sign convention, and the invariants checked; call it first to format the input.

Both tools are read-only and return finvariant's JSON-safe payload, so a client can present and auto-run them safely.

Installation

Run it with uv (no install needed):

uvx finvariant-mcp

or install from PyPI:

pip install finvariant-mcp

Configuration

Add it to your MCP client. For example:

{
  "mcpServers": {
    "finvariant": {
      "command": "uvx",
      "args": ["finvariant-mcp"]
    }
  }
}

If you installed with pip, use "command": "finvariant-mcp" with no args.

Example

An agent verifying a model it just built:

describe_schema()
  -> the field names, sign convention and the four invariant groups

check_statements(
  periods=["FY2024"],
  balance_sheet={"FY2024": {
    "total_assets": 540, "total_liabilities": 158, "total_equity": 380
  }},
)
  -> { "ok": false,
       "verdict": "FAIL - statements do not tie out",
       "findings": [ { "rule_id": "EQ.accounting_equation",
                       "expected": 538, "actual": 540, "difference": 2 } ],
       "summary": "finvariant audit - ...\n  Verdict: FAIL ..." }

Design

The server is a thin, stateless wrapper. All accounting logic lives in the finvariant library, which computes the invariants from their definitions and is validated against the published statements of several real companies. The server adds the tool schema, read-only annotations and an input-schema helper so an agent can format the input and act on the result.

Related

License

MIT. Written and maintained by Atakan Arikan, MSc Student at Tsinghua University and Politecnico di Milano.

Ver o original no GitHub

Bom para

Relacionados