# io.github.paivapiovesan/next-finance (npm · next-finance-mcp)

MCP Server for NEXT Finance ERP (finance.net.br) — browser login, wallets, accounts, transactions.

- Trust score: 60/100 (medium)
- Change this week: +41
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- npm · `next-finance-mcp`: 60/100 (this document), [markdown](https://verifymcp.io/servers/paivapiovesan-next-finance/next-finance-mcp.md), [page](https://verifymcp.io/servers/paivapiovesan-next-finance/next-finance-mcp)

## Channel facts

- Registry: `npm`
- Package: `next-finance-mcp`
- Version: `0.9.73`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Supply Chain Security**: 87/100
  - No malware found by supply-chain analysis.
  - Only part of the dependency tree could be resolved (116 of 117), so this covers what we could see, not the whole tree.
  - No install/post-install scripts declared.
  - Only part of the dependency tree could be resolved (116 of 117), so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 19/100
  - Repository check failed: the declared repository URL returned HTTP 404.
  - Provenance check failed: no build-provenance attestation is published.
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 2 days ago).
  - Security-disclosure policy not yet verified: we couldn't inspect the source repository.
- **Schema Quality & AI Usability**: 58/100
  - AI-judged instruction clarity (good).
  - Context-footprint check failed: tool/resource definitions use about 12085 tokens (~194/item across 62 items; 62 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 23/100
  - Stability observed for 7 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add paivapiovesan-next-finance -- npx -y next-finance-mcp
```

### Codex

```bash
codex mcp add paivapiovesan-next-finance -- npx -y next-finance-mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "paivapiovesan-next-finance": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "next-finance-mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add paivapiovesan-next-finance --command npx --arg -y --arg next-finance-mcp
```

### Hermes

```yaml
mcp_servers:
  paivapiovesan-next-finance:
    command: "npx"
    args: ["-y", "next-finance-mcp"]
```

### Other

```json
{
  "mcpServers": {
    "paivapiovesan-next-finance": {
      "command": "npx",
      "args": [
        "-y",
        "next-finance-mcp"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-02 (score 60, +47)

- [security regression] Provenance: unverified → fail
- [security improvement] Install scripts: unverified → pass
- [security improvement] Known CVEs: unverified → partial
- [security improvement] Malware scan: unverified → pass
- [functional regression] Tool coverage: 100 → unverified
- [functional improvement] Schema quality: unverified → good
- [functional improvement] MCP protocol: unverified → pass
- [functional improvement] Maintenance: unverified → pass
- [functional improvement] Stability: unverified → 0.20
- [functional improvement] License: unverified → pass
- [functional improvement] Dependency health: unverified → partial
- [functional] Schema quality: Schema quality not yet verified: we do not have a sandbox capture of the MCP schema this version of the package serves yet.
- [functional] Licence: MIT
- [functional] Package version: 0.9.70 → 0.9.71

### 2026-08-01 (score 13, +13)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-31 (score 0, 0)

- [functional] Tool coverage: Tool coverage not yet verified: our sandbox run of this package did not complete, so we have no tool definitions to assess.
- [functional] Schema quality: Schema quality not yet verified: our sandbox run of this package did not complete, so we have no schema to assess.
- [functional] Package version: 0.9.67 → 0.9.70

### 2026-07-29 (score 0, 0)

- [functional] Package version: 0.9.68 → 0.9.70

### 2026-07-28 (score 0, −19)

- [functional regression] Tool coverage: 100 → unverified
- [functional] First check of Schema quality: unverified
- [functional] Package version: 0.9.67 → 0.9.68

### 2026-07-27 (score 19)

First indexed and scored.

## MCP tools (62)

### `login` (~42 tokens)

Abre uma janela no browser para login seguro no NEXT Finance. As credenciais não passam pelo chat. Se já houver sessão salva, restaura automaticamente sem abrir o browser.

### `logout` (~21 tokens)

Encerra a sessão e remove os dados de sessão salvos.

### `listar_carteiras` (~22 tokens)

Lista todas as carteiras disponíveis para o usuário logado.

### `selecionar_carteira` (~76 tokens)

Seleciona uma carteira pelo nome (necessário antes de listar contas e lançamentos). Use listar_carteiras para ver os nomes disponíveis.

Input parameters:

- `nome_carteira` (string, required): Nome (ou parte do nome) da carteira (ex: 'Rodrigo', 'Mônica', 'Paiva Piovesan')

### `listar_contas` (~241 tokens)

Lista as contas ativas da carteira selecionada. As contas seguem hierarquia de 4 níveis: Moeda → Portfolio → Tipo de Conta → Conta. Portfolios: Liquidez, Previdência, Renda Fixa, Renda Variável, Tesouraria. Use os filtros para navegar nessa hierarquia.

Input parameters:

- `busca` (string): Filtra pelo nome da conta (ex: 'Inter', 'Bradesco', 'PETR4')
- `limite` (number): Contas por página (padrão: 50, máximo: 200)
- `moeda` (string): Filtra pela moeda (ex: 'BRL', 'USD', 'EUR')
- `pagina` (number): Página (começa em 1, padrão: 1)
- `portfolio` (string): Filtra pelo portfolio (ex: 'Tesouraria', 'Renda Variável', 'Previdência', 'Liquidez')
- `tipo_conta` (string): Filtra pelo tipo de conta (ex: 'Conta Corrente', 'Cartão de Crédito', 'Ações', 'CDB', 'Fundo de Previdência')

### `listar_contas_correntes` (~177 tokens)

RÁPIDO e DIRETO: lista SÓ as contas correntes da carteira, com campos mínimos (nome, banco, agência, conta, permissão e saldo de hoje). Use esta tool quando o usuário pedir 'minhas contas correntes' / 'saldo das contas' — NÃO use listar_contas (que traz a árvore inteira de centenas de contas) nem nada de Open Finance/extrato/conciliação para isso. Uma única consulta ao cadastro interno + uma consulta de saldo em lote. Passe incluir_saldo=false para a resposta mais rápida possível (sem o saldo do dia).

Input parameters:

- `busca` (string): Filtra pelo nome da conta (ex: 'Inter', 'Bradesco')
- `incluir_saldo` (boolean): Incluir o saldo de hoje de cada conta (padrão: true)

### `criar_conta` (~580 tokens)

Cria uma CONTA de QUALQUER TIPO na carteira (Conta Corrente, Poupança, Conta Caixa, Cartão de Crédito, CDB, Tesouro Direto, Ações, Fundo, Empréstimo, Conta a Pagar/Receber, etc.). Obrigatórios: tipo_conta e nome. Use listar_tipos_conta para ver os tipos válidos. Nomes (tipo_conta, portfolio, banco, moeda, país) são resolvidos para IDs. Campos bancários (banco, agência, conta) valem para contas com banco. Padrões: moeda BRL, país Brasil, data inicial hoje, saldo inicial 0. Portfólio: se omitido, o sistema atribui um padrão.

Input parameters:

- `agencia` (string): Número da agência
- `banco` (string): Nome ou número do banco (ex: 'Banco do Brasil', '001', 'Inter')
- `data_inicial` (string): Data inicial de controle YYYY-MM-DD (padrão: hoje)
- `dia_fechamento_fatura` (number): Cartão de crédito: dia do mês de fechamento da fatura (1-31)
- `dia_vencimento_fatura` (number): Cartão de crédito: dia do mês de vencimento da fatura (1-31)
- `digito_agencia` (string): Dígito da agência
- `digito_conta` (string): Dígito da conta
- `iban` (string): IBAN
- `internacional` (boolean): Cartão de crédito: se é internacional
- `juros_cheque_especial` (number): Juros do cheque especial (%)
- `limite` (number): Cartão de crédito: limite do cartão
- `limite_cheque_especial` (number): Limite do cheque especial
- `moeda` (string): Moeda (padrão: 'BRL')
- `nib` (string): NIB
- `nome` (string, required): Nome da conta — obrigatório
- `numero_cartao` (string): Cartão de crédito: número do cartão
- `numero_conta` (string): Número da conta bancária
- `observacoes` (string): Observações
- `pais` (string): País (padrão: 'Brasil')
- `portfolio` (string): Tipo de Portfólio (ex: 'Tesouraria', 'Liquidez', 'Renda Fixa', 'Renda Variável', 'Previdência')
- `saldo_inicial` (number): Saldo inicial (padrão: 0)
- `swift` (string): SWIFT
- `tipo_conta` (string, required): Tipo da conta (ex: 'Conta Corrente', 'Poupança', 'CDB', 'Cartão de Crédito') — obrigatório

### `listar_tipos_conta` (~30 tokens)

Lista os tipos de conta disponíveis (corrente, poupança, cartão, investimento etc.).

### `listar_centros_de_custo` (~52 tokens)

Lista os centros de custo da carteira. Use para descobrir nomes exatos antes de filtrar lançamentos por centro de custo.

Input parameters:

- `busca` (string): Filtra pelo nome do centro de custo

### `listar_plano_de_contas` (~113 tokens)

Lista o plano de contas da carteira (categorias de receita e despesa). Use para descobrir nomes exatos de categorias antes de buscar lançamentos por plano de contas.

Input parameters:

- `busca` (string): Filtra pelo nome do plano de contas (ex: 'Restaurante', 'Salário')
- `limite` (number): Itens por página (padrão: 100, máximo: 200)
- `pagina` (number): Página (começa em 1, padrão: 1)

### `criar_centro_de_custo` (~112 tokens)

Cria um novo centro de custo na carteira. Informe o 'nome'; opcionalmente um 'pai' (centro de custo existente, para criar como sub-centro) e uma 'descricao'.

Input parameters:

- `descricao` (string): Descrição (opcional)
- `nome` (string, required): Nome do centro de custo (ex: 'Marketing', 'Wanêssa e Rodrigo')
- `pai` (string): Centro de custo pai (nome), para criar como sub-centro (opcional)

### `criar_plano_de_contas` (~147 tokens)

Cria uma nova categoria no plano de contas. O 'pai' é OBRIGATÓRIO e define se o novo plano é de DESPESA ou RECEITA (o tipo é herdado do ramo do pai — ex.: pai 'Despesas Operacionais' cria uma despesa). Use 'listar_plano_de_contas' para achar o nome do pai.

Input parameters:

- `descricao` (string): Descrição (opcional)
- `nome` (string, required): Nome do novo plano de contas (ex: 'Streaming', 'Vale Refeição')
- `pai` (string, required): Plano de contas PAI (categoria existente) — define despesa/receita

### `buscar_lancamentos` (~380 tokens)

Busca lançamentos/transações da carteira. nome_conta é OPCIONAL — sem ele a tool agrega automaticamente todas as contas de movimento (corrente, cartão de crédito, caixa, poupança) numa única chamada, retornando o resultado consolidado. Prefira chamar UMA vez sem nome_conta a iterar por conta para um dashboard. Use plano_de_contas para filtrar por categoria (ex: 'Restaurante'). Transferências entre contas são excluídas por padrão. O retorno inclui totais (despesas/receitas/saldo) + agregações por plano_de_contas e centro_de_custo.

Input parameters:

- `apenas_despesas` (boolean): Se true, retorna só despesas
- `apenas_receitas` (boolean): Se true, retorna só receitas
- `busca` (string): Filtra pela descrição do lançamento
- `centro_de_custo` (string): Filtra por centro de custo
- `data_fim` (string): Data fim YYYY-MM-DD (padrão: hoje)
- `data_inicio` (string): Data início YYYY-MM-DD (padrão: 30 dias atrás)
- `excluir_previsoes` (boolean): Excluir lançamentos de previsão (padrão: false)
- `excluir_transferencias` (boolean): Excluir transferências entre contas (padrão: true)
- `limite` (number): Lançamentos por página (padrão: 50, máximo: 200)
- `nome_conta` (string): Nome da conta (opcional — omitir busca em todas as contas, ex: 'Nubank', 'Inter')
- `pagina` (number): Página (começa em 1, padrão: 1)
- `plano_de_contas` (string): Filtra por categoria/plano de contas (ex: 'Restaurante')

### `buscar_contas_a_pagar` (~307 tokens)

Lista os TÍTULOS A PAGAR (contas a pagar) da carteira — agrega TODAS as contas do tipo 'Conta a Pagar'. Cada título traz: vencimento, valor, moeda, fornecedor (campo 'contraparte'), conta, se está vencido e os dias de atraso/para vencer. Retorna totais_por_moeda (nunca soma moedas diferentes) e agregação por fornecedor. Use moeda='BRL' para focar no real; apenas_vencidos=true para só o que está em atraso. Janela padrão: 1 ano atrás a 1 ano à frente.

Input parameters:

- `apenas_vencidos` (boolean): Se true, retorna só títulos vencidos (em atraso)
- `busca` (string): Filtra pelo nome do fornecedor (contraparte)
- `data_fim` (string): Data fim do vencimento YYYY-MM-DD (padrão: 1 ano à frente)
- `data_inicio` (string): Data início do vencimento YYYY-MM-DD (padrão: 1 ano atrás)
- `limite` (number): Títulos por página (padrão: 50, máximo: 200)
- `moeda` (string): Filtra por moeda (ex: 'BRL'). Sem isso, retorna todas — e os totais vêm separados por moeda (nunca somados).
- `pagina` (number): Página (começa em 1, padrão: 1)

### `buscar_contas_a_receber` (~390 tokens)

Lista os TÍTULOS A RECEBER da carteira — agrega TODAS as contas do tipo 'Conta a Receber' e, por padrão, também as do tipo 'Contas em Cobrança' (cada título tem o flag em_cobranca). Cada título traz: vencimento, valor, moeda, cliente (campo 'contraparte'), conta, se está vencido e os dias de atraso/para vencer. Retorna totais_por_moeda (nunca soma moedas diferentes) e agregação por cliente. Use moeda='BRL' para focar no real; apenas_cobranca=true para SÓ os recebíveis em cobrança; apenas_vencidos=true para só os vencidos. Janela padrão: 1 ano atrás a 1 ano à frente.

Input parameters:

- `apenas_cobranca` (boolean): Se true, retorna SÓ os títulos em cobrança
- `apenas_vencidos` (boolean): Se true, retorna só títulos vencidos (em atraso)
- `busca` (string): Filtra pelo nome do cliente (contraparte)
- `data_fim` (string): Data fim do vencimento YYYY-MM-DD (padrão: 1 ano à frente)
- `data_inicio` (string): Data início do vencimento YYYY-MM-DD (padrão: 1 ano atrás)
- `incluir_cobranca` (boolean): Inclui as contas 'em Cobrança' na agregação (padrão: true)
- `limite` (number): Títulos por página (padrão: 50, máximo: 200)
- `moeda` (string): Filtra por moeda (ex: 'BRL'). Sem isso, retorna todas — e os totais vêm separados por moeda (nunca somados).
- `pagina` (number): Página (começa em 1, padrão: 1)

### `buscar_despesas_periodicas` (~195 tokens)

Lista as DESPESAS PERIÓDICAS (estimativas recorrentes) da carteira — a camada de PREVISÃO que o usuário cadastra na tela 'Despesas Periódicas' e que depois é programada em Contas a Pagar. Cada item traz: descrição, valor_estimado, moeda, dia do mês, periodicidade (Mensal/Anual…), plano de contas, centro de custo, variacao_tolerada_pct e previsoes_associadas. Retorna a estimativa_mensal_por_moeda (orçamento mensal). Use moeda='BRL' para focar no real. Distinta de buscar_contas_a_pagar (que traz os títulos já programados/reais).

Input parameters:

- `busca` (string): Filtra pela descrição (ex: 'Energisa')
- `moeda` (string): Filtra por moeda (ex: 'BRL')

### `buscar_receitas_periodicas` (~173 tokens)

Lista as RECEITAS PERIÓDICAS (estimativas recorrentes) da carteira — a camada de PREVISÃO da tela 'Receitas Periódicas', depois programada em Contas a Receber. Cada item traz: descrição, valor_estimado, moeda, dia do mês, periodicidade, plano de contas, centro de custo, variacao_tolerada_pct e previsoes_associadas. Retorna a estimativa_mensal_por_moeda. Use moeda='BRL' para focar no real. Distinta de buscar_contas_a_receber (títulos já programados/reais).

Input parameters:

- `busca` (string): Filtra pela descrição (ex: 'Aluguel')
- `moeda` (string): Filtra por moeda (ex: 'BRL')

### `conferir_previsto_realizado` (~268 tokens)

CONFERÊNCIA previsto × realizado de um mês: cruza as 3 camadas — previsto (Despesa/Receita Periódica = estimativa), programado (título em Contas a Pagar/Receber no mês, após acerto) e realizado (efetivado nas contas de movimento). Retorna por_item (descrição: previsto/programado/realizado/diferença/status, respeitando a variação tolerada) e por_categoria (orçado × realizado por plano de contas), além de resumo_por_moeda. Status: ok / acima / abaixo / pendente (sem realizado) / sem_previsao. Use para validar se as estimativas batem com a realidade. Passe moeda='BRL' para não misturar moedas. Observação: por_item casa por descrição+plano (exato); a visão por_categoria é a mais robusta.

Input parameters:

- `mes` (string, required): Mês de referência YYYY-MM (ex: '2026-06')
- `moeda` (string): Moeda (ex: 'BRL') — recomendado para não misturar moedas
- `tipo` (string, required): 'despesa' (Contas a Pagar) ou 'receita' (Contas a Receber)

### `listar_clientes` (~195 tokens)

Lista os CLIENTES da carteira (quem tem títulos a receber), ordenados pelo valor a receber. Cada cliente traz: nome, tipo (PF/PJ), quantidade de títulos, valor a receber e valor vencido. Retorna também o total_a_receber da carteira. Use busca para filtrar por nome. Para a ficha cadastral completa de um cliente (CPF/CNPJ, endereço, etc.) use buscar_contato; para registrar uma tratativa/cobrança use criar_registro_relacionamento.

Input parameters:

- `busca` (string): Filtra pelo nome do cliente
- `limite` (number): Clientes por página (padrão: 50, máximo: 200)
- `moeda` (string): Filtra por moeda dos recebíveis (ex: 'BRL'). O total a receber vem separado por moeda.
- `pagina` (number): Página (começa em 1, padrão: 1)

### `criar_lancamento` (~538 tokens)

Cria um novo lançamento (despesa ou receita) numa conta. Valor negativo = despesa, positivo = receita. Nomes (conta, plano de contas, centro de custo) são resolvidos para IDs internos automaticamente; se a busca for ambígua a tool lista as opções.

Input parameters:

- `centro_de_custo` (string): Nome do centro de custo (ex: 'Wanêssa e Rodrigo')
- `codigo_de_barras` (string): Boleto: código de barras (44 díg), se já tiver. Opcional — normalmente derivado da linha digitável.
- `cpf_cnpj_beneficiario` (string): Boleto: CPF/CNPJ do beneficiário/favorecido (opcional)
- `data` (string, required): Data do lançamento YYYY-MM-DD
- `data_emissao` (string): Data de emissão YYYY-MM-DD (opcional)
- `data_vencimento` (string): Data de vencimento YYYY-MM-DD (opcional)
- `descricao` (string, required): Descrição do lançamento
- `forma_pagamento` (string): 'Dinheiro' | 'Boleto' | 'Cartao' | 'Carteira' | 'Cheque' | 'Deposito' (auto = Boleto se informar linha_digitavel)
- `linha_digitavel` (string): Boleto: linha digitável (47/48 díg). Deriva AUTOMATICAMENTE código de barras, valor e vencimento — deixa o lançamento pronto para transmissão bancária.
- `local_de_pagamento` (string): Conta corrente de onde SAI o pagamento (nome). Obrigatório para gerar o lote de pagamento no banco.
- `manter_data_compra` (boolean): Cartão de crédito: por padrão o lançamento é movido para a data de VENCIMENTO da fatura (regra do NEXT). Use true para lançar na data literal da compra.
- `nome_conta` (string, required): Nome da conta (ex: 'Inter CC 651549')
- `nosso_numero` (string): Boleto: nosso número (opcional)
- `numero_documento` (string): Número do documento (NF, recibo, etc.)
- `observacoes` (string): Observações livres
- `plano_de_contas` (string): Nome do plano de contas (ex: 'Restaurantes')
- `previsao` (boolean): Lançamento de previsão (não realizado)? Padrão: false
- `tipo_servico` (number): Código do tipo de serviço do pagamento (opcional)
- `valor` (number, required): Valor (negativo = despesa, positivo = receita)

### `criar_transferencia` (~223 tokens)

Cria uma transferência entre duas contas — débito na conta de origem e crédito na conta de destino (o NEXT cria automaticamente os dois lados, vinculados). Use isto, NÃO criar_lancamento, quando o dinheiro sai de uma conta sua e entra em outra conta sua (ex: PIX entre contas próprias, aplicação/resgate, pagamento de fatura de cartão a partir da conta corrente). Requer permissão de edição na conta de origem. Valor sempre positivo.

Input parameters:

- `conta_destino` (string, required): Conta para onde o dinheiro VAI (ex: 'Nubank CC 9782300-2')
- `conta_origem` (string, required): Conta de onde o dinheiro SAI (ex: 'Itaú CC 08472-3')
- `data` (string, required): Data da transferência YYYY-MM-DD
- `descricao` (string): Descrição (opcional; padrão: 'Transferência para <destino>')
- `observacoes` (string): Observações livres (opcional)
- `valor` (number, required): Valor transferido (positivo)

### `editar_lancamento` (~568 tokens)

Edita um lançamento existente. Localiza pelo nome_conta + data + valor/descrição (varre TODAS as contas homônimas, inclusive em moedas diferentes — ex: as várias 'Conta a Pagar') e aplica as alterações. Se mais de um lançamento bater, a tool lista as opções para você refinar (use 'moeda' para desambiguar).

Input parameters:

- `data` (string, required): Data do lançamento YYYY-MM-DD (para localizar)
- `descricao` (string): Descrição original (substring, para localizar, opcional)
- `moeda` (string): Moeda da conta (ex: 'BRL') — desambigua contas homônimas em moedas diferentes
- `nome_conta` (string, required): Nome da conta do lançamento
- `nova_data` (string): Nova data YYYY-MM-DD
- `nova_data_emissao` (string): Nova data de emissão YYYY-MM-DD
- `nova_data_vencimento` (string): Nova data de vencimento YYYY-MM-DD
- `nova_descricao` (string): Nova descrição
- `nova_forma_pagamento` (string): 'Dinheiro' | 'Boleto' | 'Cartao' | 'Carteira' | 'Cheque' | 'Deposito'
- `nova_linha_digitavel` (string): Boleto: linha digitável (deriva código de barras, valor e vencimento; marca forma = Boleto)
- `nova_previsao` (boolean): Marcar/desmarcar como previsão
- `novas_observacoes` (string): Novas observações
- `novo_centro_de_custo` (string): Novo centro de custo (nome)
- `novo_codigo_de_barras` (string): Boleto: código de barras (44 díg), se já tiver
- `novo_cpf_cnpj_beneficiario` (string): Boleto: CPF/CNPJ do beneficiário/favorecido
- `novo_local_de_pagamento` (string): Conta corrente de onde sai o pagamento (nome) — necessário para transmitir ao banco
- `novo_nosso_numero` (string): Boleto: nosso número
- `novo_numero_documento` (string): Novo número de documento
- `novo_plano_de_contas` (string): Novo plano de contas (categoria, ex: 'Restaurantes') OU nome da conta destino (ex: '99Pay') para classificar como transferência entre contas — útil para classificar lançamentos importados pela concil…
- `novo_tipo_servico` (number): Código do tipo de serviço do pagamento
- `novo_valor` (number): Novo valor (negativo = despesa, positivo = receita)
- `valor` (number): Valor original (para localizar, opcional)

### `excluir_lancamento` (~145 tokens)

Exclui um lançamento existente. Localiza pelo trio (nome_conta + data + valor/descrição). Se mais de um lançamento bater os critérios, a tool lista as opções para você refinar. AÇÃO IRREVERSÍVEL.

Input parameters:

- `data` (string, required): Data do lançamento YYYY-MM-DD
- `descricao` (string): Descrição (substring, opcional)
- `moeda` (string): Moeda da conta (ex: 'BRL') — desambigua contas homônimas em moedas diferentes
- `nome_conta` (string, required): Nome da conta
- `valor` (number): Valor (opcional, ajuda a desambiguar)

### `anexar_arquivo_lancamento` (~252 tokens)

Anexa um arquivo (boleto PDF, comprovante, nota, imagem, etc.) a um lançamento. Localiza o lançamento pelo trio (nome_conta + data + valor/descrição) e envia o arquivo. Informe 'caminho_arquivo' (arquivo local no computador) OU 'conteudo_base64' + 'nome_arquivo'. O nome precisa ter extensão (ex: boleto.pdf).

Input parameters:

- `caminho_arquivo` (string): Caminho local do arquivo a anexar (ex: /Users/você/Downloads/boleto.pdf)
- `conteudo_base64` (string): Alternativa ao caminho: conteúdo do arquivo em base64
- `data` (string, required): Data do lançamento YYYY-MM-DD
- `descricao` (string): Descrição (substring, opcional)
- `moeda` (string): Moeda da conta (desambigua homônimas)
- `nome_arquivo` (string): Nome do arquivo com extensão (obrigatório se usar base64; senão usa o nome do caminho)
- `nome_conta` (string, required): Nome da conta do lançamento
- `valor` (number): Valor (opcional, ajuda a desambiguar)

### `listar_anexos_lancamento` (~122 tokens)

Lista os arquivos anexados a um lançamento (nome, extensão, tamanho, URL). Localiza pelo trio (nome_conta + data + valor/descrição).

Input parameters:

- `data` (string, required): Data do lançamento YYYY-MM-DD
- `descricao` (string): Descrição (substring, opcional)
- `moeda` (string): Moeda da conta (desambigua homônimas)
- `nome_conta` (string, required): Nome da conta do lançamento
- `valor` (number): Valor (opcional, ajuda a desambiguar)

### `remover_anexo_lancamento` (~173 tokens)

Remove um ou mais anexos de um lançamento. Localiza pelo trio (nome_conta + data + valor/descrição) e remove os arquivos por nome COM extensão (ex: 'boleto.pdf'). Use 'listar_anexos_lancamento' para ver os nomes exatos.

Input parameters:

- `data` (string, required): Data do lançamento YYYY-MM-DD
- `descricao` (string): Descrição (substring, opcional)
- `moeda` (string): Moeda da conta (desambigua homônimas)
- `nome_conta` (string, required): Nome da conta do lançamento
- `nomes_arquivo` (array, required): Nomes dos anexos a remover, com extensão (ex: ['boleto.pdf'])
- `valor` (number): Valor (opcional, ajuda a desambiguar)

### `importar_documento_recebido` (~481 tokens)

Importa documento(s) fiscal(is) recebido(s) por XML no NEXT Business (Compras & Despesas → Documentos Recebidos): NF-e, NFC-e ou NFS-e. O NEXT parseia o XML e cria o documento. Informe 'caminho_arquivo' (um XML local), 'diretorio' (importa TODOS os .xml da pasta, em lote), ou 'conteudo_base64' + 'nome_arquivo'. CLASSIFICAÇÃO (só para UM arquivo): para o documento já sair lançado no Finance, informe 'conta_pagamento' (conta/cartão), e se for o caso 'parcelas' + 'primeiro_vencimento', além de 'plano_de_contas' e 'centro_de_custo'. Se o usuário NÃO disse onde/como pagar nem a classificação, PERGUNTE antes (conta/cartão, à vista ou parcelado + 1º vencimento, plano de contas, centro de custo) — não invente.

Input parameters:

- `caminho_arquivo` (string): Caminho local de UM arquivo XML (ex: /Users/você/Downloads/nota.xml)
- `centro_de_custo` (string): Centro de custo para a classificação (ex: 'Wanêssa e Rodrigo')
- `conta_pagamento` (string): Conta/cartão onde o documento será pago (nome, ex: '15 XP'). Dispara a classificação no Finance.
- `conteudo_base64` (string): Alternativa: conteúdo do XML em base64
- `diretorio` (string): Pasta local — importa TODOS os .xml dela (lote)
- `forma_pagamento` (number): Código da forma de pagamento (default 48 = Cartão de Crédito)
- `nome_arquivo` (string): Nome do arquivo .xml (obrigatório se usar base64)
- `parcelas` (number): Nº de parcelas (default 1 = à vista)
- `periodicidade` (number): Código de periodicidade das parcelas (default 3 = Mensal)
- `plano_de_contas` (string): Plano de contas para a classificação (ex: 'Manutenção Veículo')
- `primeiro_vencimento` (string): Vencimento da 1ª parcela YYYY-MM-DD (default: vencimento do documento)

### `cadastrar_documento_recebido` (~655 tokens)

Cadastra MANUALMENTE um documento fiscal recebido no NEXT Business (Compras & Despesas → Documentos Recebidos) a partir de dados lidos de um PDF/impressão/imagem — quando NÃO há XML nem link importável (ex.: NFC-e cuja consulta foi protegida por reCAPTCHA, ou NF3-e de energia). O ASSISTENTE lê o documento e passa os campos. Tipos: 'NFCe', 'NFe', 'NFSe', 'Energia Elétrica' (NF3-e), 'Recibo', 'Cupom Fiscal', etc. O fornecedor precisa estar cadastrado (senão use criar_contato). ATENÇÃO a valores negativos (ex.: energia compensada na NF3-e reduz o total). PERGUNTE ao usuário a DATA DE EMISSÃO quando ela não estiver visível no documento, e a FORMA DE PAGAMENTO (e conta/cartão) — não invente. Passe 'fornecedor_cnpj' para vincular a filial certa; se for filial nova da mesma empresa, inclua também o endereço para cadastrá-la.

Input parameters:

- `centro_de_custo` (string): Centro de custo para classificar (opcional)
- `conta_pagamento` (string): Conta/cartão onde foi pago (nome). Acompanha a forma de pagamento.
- `data_emissao` (string, required): Data de emissão YYYY-MM-DD
- `data_vencimento` (string): Vencimento YYYY-MM-DD (default: emissão)
- `endereco_bairro` (string): Bairro da filial
- `endereco_cep` (string): CEP da filial (opcional)
- `endereco_cidade` (string): Cidade da filial
- `endereco_logradouro` (string): Rua/avenida da filial (para adicionar endereço novo)
- `endereco_numero` (string): Número do endereço da filial
- `endereco_uf` (string): UF da filial (ex: 'MG')
- `forma_pagamento` (string): Como foi pago: 'Vale Alimentação', 'Cartão', ou o código. PERGUNTE ao usuário se não estiver claro.
- `fornecedor` (string, required): Nome do fornecedor (deve estar cadastrado, ex: 'Carrefour', 'Cemig')
- `fornecedor_cnpj` (string): CNPJ da filial emitente — vincula ao endereço certo; se for filial nova (mesma raiz) e você passar o endereço, ela é adicionada ao fornecedor.
- `fornecedor_ie` (string): Inscrição Estadual da filial (ao adicionar endereço novo)
- `informacao_adicional` (string): Observações (ex: chave de acesso, protocolo)
- `itens` (array, required): Itens do documento
- `numero` (string, required): Número do documento
- `plano_de_contas` (string): Plano de contas para classificar (opcional)
- `tipo` (string, required): Tipo do documento: 'NFCe', 'NFe', 'NFSe', 'Energia Elétrica', 'Recibo', 'Cupom Fiscal'…
- `valor` (number, required): Valor TOTAL do documento (líquido, já considerando itens negativos como energia compensada)

### `classificar_documento_recebido` (~316 tokens)

Classifica o pagamento de um documento recebido JÁ importado (Compras & Despesas): define a conta/cartão, parcelas e vencimentos, e o plano de contas + centro de custo — deixando-o lançado no Finance. Localiza o documento pelo 'numero' (+ 'fornecedor' se houver mais de um). Se o usuário não informou conta/parcelas/classificação, PERGUNTE antes.

Input parameters:

- `centro_de_custo` (string): Centro de custo (ex: 'Wanêssa e Rodrigo')
- `conta_pagamento` (string, required): Conta/cartão onde será pago (nome, ex: '15 XP')
- `data_fim` (string): Fim do período de busca YYYY-MM-DD
- `data_inicio` (string): Início do período de busca YYYY-MM-DD (default: últimos 30 dias)
- `forma_pagamento` (number): Código da forma de pagamento (default 48 = Cartão)
- `fornecedor` (string): Nome do fornecedor (para desambiguar, opcional)
- `numero` (string, required): Número do documento (ex: '1580')
- `parcelas` (number): Nº de parcelas (default 1 = à vista)
- `periodicidade` (number): Código de periodicidade (default 3 = Mensal)
- `plano_de_contas` (string): Plano de contas (ex: 'Manutenção Veículo')
- `primeiro_vencimento` (string): Vencimento da 1ª parcela YYYY-MM-DD

### `listar_moedas` (~74 tokens)

Lista as moedas disponíveis no NEXT Finance (ex: BRL, USD, EUR). Use 'busca' para filtrar por nome, sigla ou símbolo.

Input parameters:

- `busca` (string): Filtra por nome, sigla ou símbolo da moeda (ex: 'BRL', 'dólar', '$')

### `permissao_conta` (~111 tokens)

Verifica a permissão do usuário logado sobre uma conta. Retorna 'Negar' (oculta), 'Ver' (somente leitura) ou 'Editar' (acesso total). O MCP respeita essas permissões automaticamente: contas 'Negar' não aparecem em listagens, e tentativas de criar/editar/excluir lançamento em conta 'Ver' são rejeitadas.

Input parameters:

- `nome_conta` (string, required): Nome da conta (ex: 'Inter CC 651549')

### `consultar_saldo` (~111 tokens)

Consulta o saldo de UMA conta numa data específica (padrão: hoje). Use 'saldo_carteira' para o snapshot consolidado de todas as contas. Retorna o saldo acumulado do dia (ex: R$ -16.049,49 no Itaú em 06/06/2026).

Input parameters:

- `data` (string): Data YYYY-MM-DD (padrão: hoje)
- `nome_conta` (string, required): Nome da conta (ex: 'Inter CC 651549')

### `saldo_carteira` (~112 tokens)

Snapshot completo de saldos da carteira numa data (default: hoje), agrupado em árvore Moeda → Portfolio → Tipo de Conta → Conta. Equivale à tela 'Outras Contas' do NEXT Finance. Mostra patrimônio total por moeda (BRL, USD, EUR, etc.) e breakdown por categoria (Renda Fixa, Renda Variável, Tesouraria, Liquidez, Previdência).

Input parameters:

- `data` (string): Data YYYY-MM-DD (padrão: hoje)

### `ultimo_preco_produto` (~227 tokens)

Histórico de preços de um produto — responde 'qual o último preço que paguei pelo produto X?'. Por padrão retorna 1 linha por fornecedor com a compra mais recente, ordenado por data desc. Use 'agrupar_por_fornecedor=false' para listar TODAS as compras. Período default: últimos 12 meses. Fonte: NEXT Business (NFCe/NF-e + cadastro de produtos).

Input parameters:

- `agrupar_por_fornecedor` (boolean): true (default) = 1 linha por fornecedor com a compra mais recente; false = lista completa
- `busca` (string, required): Nome ou parte do nome do produto (ex: 'bombom garoto', 'café')
- `data_fim` (string): YYYY-MM-DD (padrão: hoje)
- `data_inicio` (string): YYYY-MM-DD (padrão: 12 meses atrás)
- `limite` (number): Máximo de entradas retornadas (padrão: 20)
- `nome_fornecedor` (string): Restringe a um fornecedor (opcional)

### `resumo_categoria` (~170 tokens)

Resumo de gastos/receitas numa categoria do plano de contas — responde 'quanto gastei com Restaurantes em maio?'. Retorna total de despesas/receitas/saldo do período, breakdown por mês, por conta, por centro de custo e top 15 descrições. Período default: últimos 30 dias.

Input parameters:

- `apenas_despesas` (boolean): Filtrar só despesas
- `apenas_receitas` (boolean): Filtrar só receitas
- `data_fim` (string): YYYY-MM-DD (padrão: hoje)
- `data_inicio` (string): YYYY-MM-DD (padrão: 30 dias atrás)
- `plano_de_contas` (string, required): Nome da categoria (ex: 'Restaurantes', 'Combustível', 'Salário')

### `resumo_centro_de_custo` (~141 tokens)

Resumo de gastos/receitas num centro de custo — responde 'despesas e receitas do CC Pedro Tobias?'. Retorna total de despesas/receitas/saldo, breakdown por mês, por plano de contas, por conta e top 15 descrições. Período default: últimos 30 dias.

Input parameters:

- `centro_de_custo` (string, required): Nome do centro de custo (ex: 'Pedro Tobias', 'Wanêssa e Rodrigo')
- `data_fim` (string): YYYY-MM-DD (padrão: hoje)
- `data_inicio` (string): YYYY-MM-DD (padrão: 30 dias atrás)

### `listar_contas_open_finance` (~62 tokens)

Lista as contas da carteira que possuem vínculo Open Finance ativo (integração via Pluggy/OF). Retorna nome da conta, banco, tipo e se exige MFA. Não chama a API REST — usa os dados de cadastro da conta diretamente.

### `verificar_open_finance` (~67 tokens)

Verifica se uma conta específica tem vínculo Open Finance configurado e se exige MFA. Usa dados de cadastro (offline).

Input parameters:

- `nome_conta` (string, required): Nome da conta (ex: 'Inter CC 651549', 'Nubank CC 9782300-2')

### `atualizar_open_finance` (~88 tokens)

Dispara uma sincronização Open Finance para a conta — puxa os lançamentos mais recentes do banco via Pluggy. Após sucesso, use 'buscar_lancamentos' para ver os novos dados. Pode levar alguns segundos (chamada assíncrona ao banco).

Input parameters:

- `nome_conta` (string, required): Nome da conta a sincronizar (ex: 'Inter CC 651549')

### `iniciar_open_finance_qr` (~99 tokens)

Abre uma janela local no navegador com o widget Pluggy Connect para autenticar uma conta Open Finance que exige MFA (ex: Inter, que pede leitura de QR Code no Super App). Após o usuário concluir a autenticação, a janela fecha sozinha e a conta fica pronta para 'obter_extrato_open_finance'.

Input parameters:

- `nome_conta` (string, required): Nome da conta (ex: 'Inter CC 651549')

### `conectar_open_finance` (~151 tokens)

Conecta uma conta ao banco via Open Finance (Pluggy) pela PRIMEIRA vez. Fluxo INTERATIVO: abre o widget Pluggy Connect no navegador local, o USUÁRIO escolhe o banco e autentica (senha/MFA no app do banco), e o MCP salva o vínculo e mapeia a conta. Se o banco trouxer VÁRIAS contas, retorna a lista para associar cada uma com associar_conta_open_finance. Para renovar MFA de conta já conectada, use iniciar_open_finance_qr.

Input parameters:

- `nome_conta` (string, required): Nome da conta NEXT a conectar (ex: 'Nubank CC 9782300-2')

### `listar_contas_do_item_open_finance` (~75 tokens)

Lista as contas bancárias trazidas por uma conexão Open Finance de uma conta (para associar). Retorna cada conta OF com id e descrição — use o id em associar_conta_open_finance.

Input parameters:

- `nome_conta` (string, required): Nome da conta NEXT que tem a conexão Open Finance

### `associar_conta_open_finance` (~104 tokens)

Associa (mapeia) uma conta bancária vinda do Open Finance a uma conta do NEXT — associação CONTA A CONTA. Use o id da conta OF obtido em conectar_open_finance ou listar_contas_do_item_open_finance.

Input parameters:

- `conta_open_finance` (string, required): Id da conta bancária do Open Finance a associar
- `nome_conta` (string, required): Nome da conta NEXT que receberá o vínculo

### `desassociar_conta_open_finance` (~79 tokens)

Remove o vínculo Open Finance de uma conta (desvincula a conexão bancária). Use quando a associação ficou errada ou o vínculo travou — depois dá para reconectar com 'conectar_open_finance'.

Input parameters:

- `nome_conta` (string, required): Nome da conta NEXT a desvincular do Open Finance

### `obter_extrato_open_finance` (~156 tokens)

Solicita ao banco (via Open Finance) o extrato de uma conta no período. Diferente de 'atualizar_open_finance' (que só pega o mais recente), permite especificar um intervalo de datas. Default: últimos 30 dias. Após sucesso, a conciliação fica pendente no NEXT — finalize no app para os lançamentos aparecerem em 'buscar_lancamentos'.

Input parameters:

- `data_fim` (string): Data fim YYYY-MM-DD (padrão: hoje)
- `data_inicio` (string): Data início YYYY-MM-DD (padrão: 30 dias atrás)
- `nome_conta` (string, required): Nome da conta (ex: 'Inter CC 651549')

### `buscar_despesas` (~226 tokens)

Lista documentos recebidos (NFCe, NF-e, etc.) do NEXT Business no período. Use 'nome_fornecedor' para filtrar por fornecedor. Use 'com_itens: true' para incluir os produtos/serviços de cada documento. Retorna totais de valor e valor líquido do período.

Input parameters:

- `busca` (string): Filtra por número do documento ou tipo
- `com_itens` (boolean): Se true, inclui os itens/produtos de cada documento (padrão: false)
- `data_fim` (string): Data fim YYYY-MM-DD (padrão: hoje)
- `data_inicio` (string): Data início YYYY-MM-DD (padrão: 30 dias atrás)
- `limite` (number): Documentos por página (padrão: 50, máximo: 200)
- `nome_fornecedor` (string): Filtra por nome do fornecedor (ex: 'Supermercados BH', 'Epa')
- `pagina` (number): Página (começa em 1, padrão: 1)

### `buscar_itens_despesa` (~237 tokens)

Busca produtos e serviços dentro dos documentos recebidos (NFCe). Ideal para: 'onde comprei leite?', 'quanto paguei por café em cada fornecedor?'. Use 'busca' para filtrar pelo nome/descrição do produto. Use 'nome_fornecedor' para restringir a um fornecedor específico. Cada item retorna o documento de origem (data, número, fornecedor).

Input parameters:

- `busca` (string): Filtra pelo nome/descrição do produto ou serviço (ex: 'leite', 'café', 'detergente')
- `data_fim` (string): Data fim YYYY-MM-DD (padrão: hoje)
- `data_inicio` (string): Data início YYYY-MM-DD (padrão: 1º do mês atual)
- `limite` (number): Itens por página (padrão: 50, máximo: 200)
- `nome_fornecedor` (string): Restringe a um fornecedor específico (ex: 'Supermercados BH', 'Epa')
- `pagina` (number): Página (começa em 1, padrão: 1)

### `buscar_compras_produto` (~199 tokens)

Busca compras de produtos agrupadas por produto e fornecedor. Use 'busca' para filtrar pelo nome do produto (ex: 'bombom garoto', 'arroz'). Use 'pessoa_id' para filtrar por fornecedor específico. Ideal para ver histórico de compras, comparar preços e rastrear aquisições.

Input parameters:

- `busca` (string): Filtra pelo nome do produto (ex: 'bombom garoto', 'leite')
- `data_fim` (string): Data fim YYYY-MM-DD (padrão: hoje)
- `data_inicio` (string): Data início YYYY-MM-DD (padrão: 1º do mês atual)
- `limite` (number): Itens por página (padrão: 50, máximo: 200)
- `pagina` (number): Página (começa em 1, padrão: 1)
- `pessoa_id` (string): ID do fornecedor (opcional)

### `listar_conciliacoes` (~61 tokens)

Lista as conciliações bancárias em andamento na carteira (criadas por extrato Open Finance ou importação de arquivo). Mostra conta, banco, número de transações e período. Use antes de executar/detalhar uma conciliação.

### `detalhar_conciliacao` (~84 tokens)

Detalha os lançamentos pendentes de uma conciliação. Mostra cada transação do extrato, se é nova (não existe no NEXT) ou já existe, e se tem match automático com um lançamento existente.

Input parameters:

- `nome_conta` (string, required): Nome da conta com conciliação ativa (ex: 'Inter CC 651549')

### `associar_conciliacao` (~105 tokens)

Marca as linhas pendentes de uma conciliação para que ela possa ser finalizada. Confirma as linhas com match automático e marca as sem match como novo lançamento. Necessário rodar ANTES de executar_conciliacao (senão a finalização é recusada com 'Existe algum lançamento para conciliar desmarcado').

Input parameters:

- `nome_conta` (string, required): Nome da conta com conciliação ativa (ex: 'Inter CC 651549')

### `executar_conciliacao` (~110 tokens)

Finaliza (executa) a conciliação de uma conta via Concluir — aplica os lançamentos do extrato na conta. AÇÃO IRREVERSÍVEL. Requer permissão de edição. Rode 'associar_conciliacao' antes. Pode levar mais de 1 minuto. Os lançamentos novos podem ficar SEM classificação — use editar_lancamento depois.

Input parameters:

- `nome_conta` (string, required): Nome da conta (ex: 'Inter CC 651549')

### `reiniciar_conciliacao` (~70 tokens)

Reinicia uma conciliação em andamento (descarta o progresso e re-busca os lançamentos do extrato). Útil quando algo deu errado na conciliação atual.

Input parameters:

- `nome_conta` (string, required): Nome da conta (ex: 'Inter CC 651549')

### `listar_classes_de_cadastro` (~89 tokens)

Lista as Classes de Cadastro (Tags) disponíveis para classificar um contato — ex: 'Clientes e Empregadores', 'Fornecedores', 'Correntista'. A classe é OBRIGATÓRIA ao criar um contato (criar_contato). Use antes de criar_contato para escolher a classe correta.

Input parameters:

- `busca` (string): Filtra pelo nome da classe

### `criar_contato` (~401 tokens)

Cria um CONTATO (pessoa física ou jurídica) no NEXT, seguindo as regras do sistema. OBRIGATÓRIOS: tipo (PF/PJ), nome (PF=nome completo; PJ=razão social) e classe_de_cadastro (use listar_classes_de_cadastro para ver as opções). Demais campos são opcionais mas recomendados (CPF/CNPJ, e-mail, telefone, endereço). Nomes (classe, ramo, país) são resolvidos para IDs internos.

Input parameters:

- `bairro` (string): Bairro
- `celular` (string): Celular (PF)
- `cep` (string): CEP (endereço)
- `chave_pix` (string): Chave PIX
- `cidade` (string): Cidade
- `classe_de_cadastro` (string, required): Classe de Cadastro (OBRIGATÓRIA) — ex: 'Clientes e Empregadores', 'Fornecedores'
- `cnae` (string): Código CNAE principal (PJ)
- `cnpj_raiz` (string): Raiz do CNPJ, 8 dígitos (PJ)
- `complemento` (string): Complemento
- `cpf` (string): CPF (PF)
- `email` (string): E-mail
- `estado` (string): Estado/UF
- `logradouro` (string): Rua/Avenida
- `nome` (string, required): PF: nome completo | PJ: razão social (obrigatório)
- `nome_fantasia` (string): Nome fantasia (PJ)
- `numero` (string): Número
- `observacoes` (string): Observações
- `pais` (string): País (padrão: Brasil)
- `ramo_atividade` (string): Ramo de atividade (PJ) — ex: 'Serviços'
- `telefone` (string): Telefone
- `tipo` (string, required): 'PF' (pessoa física) ou 'PJ' (pessoa jurídica)

### `buscar_contato` (~251 tokens)

Busca os DADOS CADASTRAIS de um contato (pessoa física/jurídica) pelo nome na Central de Relacionamento. A busca casa o termo em qualquer parte do nome (ex: 'Verdemar' acha 'ORGANIZAÇÃO VERDEMAR LTDA'). Com 1 resultado (ou nome exato) retorna a FICHA COMPLETA: para PF — CPF, RG, profissão, aniversário, e-mail, telefone, celular, endereço completo (logradouro, bairro, cidade/UF, CEP), chave PIX, redes sociais, observações; para PJ — CNPJ raiz, ramo/CNAE e cada estabelecimento com CNPJ, inscrição estadual (IE), inscrição municipal (IM) e endereço. Sempre inclui os registros CRM em aberto e os contratos vinculados. Com vários resultados, retorna lista enxuta (nome/tipo/cidade/e-mail) para refinar. Sem resultados, orienta os campos para cadastro. Use antes de criar_registro_relacionamento para localizar o contato e ver se já há tratativas abertas.

Input parameters:

- `busca` (string, required): Nome (ou parte) do contato (ex: 'Rodrigo', 'Instituto Beneficente')

### `criar_registro_relacionamento` (~369 tokens)

Cria um registro de atividade na Central de Relacionamento (Lead, Oportunidade, Atendimento, etc). Localiza o contato pelo nome automaticamente. Se o contato já tiver registros EM ABERTO, retorna um aviso e NÃO cria (passe ignorar_abertos=true para criar mesmo assim). Campos com nome (tipo, origem, situação, prioridade, responsável) são resolvidos para IDs; se inválidos, a tool lista as opções válidas. Situação padrão: '0 - Entrar em Contato'. Prioridade padrão: 'Pendente de Classificação'. Data padrão: hoje.

Input parameters:

- `contato` (string): Pessoa de contato (texto livre, opcional)
- `data` (string): Data YYYY-MM-DD (padrão: hoje)
- `descricao` (string, required): Descrição do registro
- `ignorar_abertos` (boolean): Se true, cria mesmo havendo registros em aberto para o contato
- `nome_contato` (string, required): Nome do contato (deve já existir no cadastro)
- `origem` (string, required): Origem (ex: 'WhatsApp', 'E-mail', 'Telefone', 'Indicação')
- `prioridade` (string): Prioridade (padrão: 'Pendente de Classificação'; outras: Alta, Média, Normal, Urgente)
- `responsavel` (string, required): Nome do responsável (usuário da carteira, ex: 'Maraize', 'Lara')
- `situacao` (string): Situação/etapa (padrão: '0 - Entrar em Contato')
- `tipo` (string, required): Tipo de registro (ex: 'Lead NEXT', 'Oportunidade Comercial', 'Atendimento Técnico')
- `titulo` (string, required): Título do registro

### `buscar_relacionamentos` (~315 tokens)

Central de Relacionamento (CRM) — lista as atividades (Leads, Oportunidades, Atendimentos, Cancelamentos) no período. Ideal para 'resumo das atividades da semana/mês'. Retorna agregações por tipo, situação (funil), responsável e origem, além da lista de atividades. Período default: últimos 30 dias. Filtros opcionais: tipo, situacao, responsavel, origem, busca.

Input parameters:

- `busca` (string): Filtra por título, nome do cliente ou contato
- `data_fim` (string): Data fim YYYY-MM-DD (padrão: hoje)
- `data_inicio` (string): Data início YYYY-MM-DD (padrão: 30 dias atrás)
- `limite` (number): Atividades por página (padrão: 50, máximo: 200)
- `origem` (string): Filtra por origem (ex: 'WhatsApp', 'E-mail', 'Telefone')
- `pagina` (number): Página (começa em 1, padrão: 1)
- `responsavel` (string): Filtra por responsável (ex: 'Maraize', 'Débora', 'Lara')
- `situacao` (string): Filtra por situação/etapa do funil (ex: 'Finalizado', 'Envio de Informações')
- `tipo` (string): Filtra por tipo (ex: 'Lead', 'Oportunidade', 'Atendimento', 'Cancelamento')

### `detalhar_relacionamento` (~112 tokens)

Detalha UMA atividade da Central de Relacionamento pelo número, incluindo todas as interações registradas e itens de agenda. Use 'buscar_relacionamentos' primeiro para achar o número.

Input parameters:

- `data_fim` (string): Data fim da busca YYYY-MM-DD (padrão: hoje)
- `data_inicio` (string): Data início da busca YYYY-MM-DD (padrão: 12 meses atrás)
- `numero` (number, required): Número da atividade (ex: 1602)

### `diagnostico_carteira` (~109 tokens)

Raio-x da carteira para CONDUZIR o cliente: o que já está montado (contas por tipo, estrutura, Open Finance) × o que falta × pendências (conciliações), com uma lista de 'proximos_passos' sugeridos. Use ao INÍCIO de um atendimento/onboarding, ou quando o cliente perguntar 'e agora?' / 'por onde começo?' — e proponha ativamente o próximo passo em vez de esperar a pergunta.

### `insight_do_dia` (~79 tokens)

Retorna UM insight/dica curto e personalizado sobre a carteira (vencimento/pendência/oportunidade/observação), para a SofIA ABRIR a conversa proativamente. Chame na PRIMEIRA interação de uma conversa, antes de esperar a pergunta do cliente, e apresente o insight de forma curta e acolhedora.

### `ajuda` (~147 tokens)

Responde dúvidas de USO do NEXT Finance/Business consultando o manual oficial do sistema (base de conhecimento embarcada). Use SEMPRE que o usuário perguntar 'como faço...', 'onde fica...', 'como funciona...', 'como cadastro/lanço/conecto/emito...' ou pedir o passo a passo de qualquer funcionalidade. Retorna o(s) artigo(s) do manual para você responder com o procedimento correto — não inventar. Sem argumento (ou 'índice'), lista todos os tópicos disponíveis. Não exige login.

Input parameters:

- `pergunta` (string): A dúvida do usuário em linguagem natural (ex: 'como conectar meu banco por open finance'). Vazio = lista os tópicos.

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/paivapiovesan-next-finance/next-finance-mcp#diagnostics

## Score history

- 2026-08-03: 60
- 2026-08-02: 60
- 2026-08-01: 13
- 2026-07-31: 0
- 2026-07-29: 0
- 2026-07-28: 0
- 2026-07-27: 19

## Links

- npm package: https://www.npmjs.com/package/next-finance-mcp
- Socket report: https://socket.dev/npm/package/next-finance-mcp
- Changelog RSS feed: https://verifymcp.io/servers/paivapiovesan-next-finance/next-finance-mcp/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/paivapiovesan-next-finance/next-finance-mcp/changelog.json
- HTML version of this page: https://verifymcp.io/servers/paivapiovesan-next-finance/next-finance-mcp