Frihet

Servidor MCP de gestão empresarial nativo em IA — 31 ferramentas para faturamento, despesas, clientes, produtos, orçamentos e conformidade fiscal. 40 moedas, OCR, Stripe Connect. Licenciado sob MIT.

GitHub

Experimente este MCPPatrocinado

Documentação

Servidor MCP nativo com IA para gestão empresarial.
Servidor MCP nativo con IA para gestión empresarial.

_{Funciona com Claude · ChatGPT · Cursor · Windsurf · Cline · Antigravity · Codex · Copilot · Gemini CLI — e qualquer cliente compatível com MCP.}

Frihet MCP — talk to your ERP in natural language

Distribuição

Canal	Status	Instalação
npm	Ativo	`npx @frihet/mcp-server`
Endpoint remoto	Ativo	`https://mcp.frihet.io/mcp` (instalação zero, OAuth ou chave de API)
Smithery	Ativo	smithery.ai/servers/frihet/frihet-mcp
MCP Registry	Ativo	registry.modelcontextprotocol.io
GitHub MCP Registry	Ativo	github.com/mcp/io.frihet/erp
Glama	Ativo	glama.ai/mcp/servers/Frihet-io/frihet-mcp
mcp.so	Auto-indexado (não verificado)	mcp.so — indexa a partir do npm + GitHub
PulseMCP	Auto-indexado (não verificado)	pulsemcp.com — indexa a partir do npm + GitHub
Cursor Marketplace	Em breve	cursor.com/marketplace
ChatGPT Apps	Em breve	chatgpt.com
Anthropic Claude Directory	Em breve	claude.ai/settings/connectors

Verdade da superfície: o catálogo contém 158 operações canônicas. O perfil completo local serve 163 nomes de ferramentas, 11 recursos e 10 prompts (158 operações canônicas mais 5 aliases fiscais). O perfil agrupado hospedado serve 166 nomes de ferramentas, 7 recursos e 10 prompts (os mesmos nomes mais 3 ferramentas de descoberta, com recursos apoiados por API mantidos apenas localmente). O perfil OpenAI revisado separadamente serve 33 nomes de ferramentas, 0 recursos e 0 prompts. A associação ao catálogo não é uma promessa de que uma API de suporte esteja habilitada para todos os espaços de trabalho.

O que é isto

Um servidor MCP que conecta seu assistente de IA ao Frihet. Crie faturas conversando. Consulte despesas em linguagem natural. Gerencie todo o seu negócio a partir do seu IDE.

You:     "Create an invoice for TechStart SL, 40 hours of consulting at 75 EUR/hour, due March 1st"
Claude:  Done. Invoice INV-2026-089 created. Total: 3,000.00 EUR + 21% IVA = 3,630.00 EUR.

158 operações canônicas. Cinco aliases fiscais. Dez prompts. O pacote local serve 11 recursos; o Worker hospedado serve deliberadamente os 7 recursos estáticos, enquanto os recursos de espaço de trabalho apoiados por API permanecem apenas no perfil local.

Experimente instantaneamente (sem cadastro)

Teste sem configuração — sem conta, sem chave de API:

FRIHET_DEMO=1 npx -y @frihet/mcp-server

No modo demo, o servidor responde a partir de exemplos realistas (faturas em espanhol com IVA/IGIC, despesas, clientes, produtos, uma conta bancária e mais) — cada registro usa IDs com prefixo demo_ e o servidor imprime um banner DEMO MODE na inicialização. Nada é persistido e nenhuma chamada de rede é feita. Gravações são simuladas e ações fiscais (e-invoice, VeriFactu, TicketBAI, FACe, folha de pagamento) retornam uma simulação claramente rotulada — nunca um envio real a qualquer autoridade tributária.

Quando estiver pronto para seus dados reais, remova a flag e adicione sua chave (app.frihet.io → Configurações → Chaves de API). Veja Instalação abaixo.

Para agentes de IA

Se você é um agente lendo este repositório em vez de uma pessoa lendo uma página, tudo o que você precisa é legível por máquina e gerado a partir do servidor em execução — você não precisa analisar este README.

O quê	Onde
Contrato de integração: início rápido por cliente, autenticação, fluxo de trabalho seguro, listas de ferramentas com autoridade humana, recuperação de erros	`docs/agent-onboarding.json` — também incluído no pacote npm
Verdade de capacidade por ferramenta: `callability`, `writesFrihet`, `externalInteraction`, `externalSideEffects`	`_meta["io.frihet/capability"]` em cada entrada de `tools/list`
Como se comportar uma vez conectado	a string `instructions` retornada por `initialize` — seu cliente a entrega a você automaticamente

Três regras que o contrato codifica, em resumo:

Oriente-se antes de agir. get_business_context e o recurso frihet://tax/rates decidem o tratamento fiscal correto. Não recupere uma taxa de imposto espanhola da memória.
Rascunho, mostre, pare. create_invoice, create_quote e create_credit_note todos usam como padrão status=draft — sem número fiscal, sem hash, nada enviado a uma autoridade tributária. Apresente o rascunho e devolva o controle.
Autoridade humana não é sua para assumir. Qualquer ferramenta com um externalSideEffects não vazio alcança a caixa de entrada de um cliente, um webhook, dinheiro ou AEAT / VeriFactu / TicketBAI / FACe. Várias também aceitam confirm=true; essa flag registra uma decisão humana — nunca a defina para satisfazer seu próprio plano.

docs/agent-onboarding.json é regenerado a partir da superfície ativa por npm run generate:agent-onboarding e controlado no CI por npm run gate:agent-onboarding, portanto suas listas e contagens de ferramentas não podem divergir do servidor.

Instalação

Uma linha (Claude Code, Cursor, Copilot, Codex, Windsurf, Gemini CLI e mais)

npx skills add Frihet-io/frihet-mcp

Plugin Claude Code (skill + servidor MCP em uma única instalação)

Este repositório também é um plugin Claude Code (frihet-erp): instalá-lo conecta tanto a skill de gestão empresarial quanto o servidor MCP.

# Try it locally
claude --plugin-dir /path/to/frihet-mcp

A disponibilidade no marketplace está pendente. Use o comando de plugin local acima ou o comando MCP do Claude Code abaixo para conectar hoje.

Invocação da skill: /frihet-erp:frihet-mcp. O .mcp.json incluído inicia @frihet/mcp-server via npx — defina FRIHET_API_KEY no seu ambiente (obtenha um em app.frihet.io → Configurações → Chaves de API).

Claude Code — um comando

claude mcp add frihet -s user -e FRIHET_API_KEY=fri_your_key_here -- npx -y @frihet/mcp-server
claude mcp list          # verify: frihet ✓ Connected

A CLI é dona do arquivo de configuração, então não há nada para editar manualmente e nenhum caminho para errar. (O escopo do usuário grava ~/.claude.json, não ~/.claude/mcp.json.)

Codex CLI — um comando

codex mcp add frihet --env FRIHET_API_KEY=fri_your_key_here -- npx -y @frihet/mcp-server
codex mcp list           # verify

A configuração do Codex é TOML, não JSON. codex mcp add grava:

[mcp_servers.frihet]
command = "npx"
args = ["-y", "@frihet/mcp-server"]

[mcp_servers.frihet.env]
FRIHET_API_KEY = "fri_your_key_here"

Colar um bloco JSON mcpServers em ~/.codex/config.toml é um erro de análise TOML que derruba toda a sua configuração do Codex, não apenas este servidor. Use o comando acima.

Claude Desktop, Cursor, Windsurf, Cline — configuração JSON

{
  "mcpServers": {
    "frihet": {
      "command": "npx",
      "args": ["-y", "@frihet/mcp-server"],
      "env": {
        "FRIHET_API_KEY": "fri_your_key_here"
      }
    }
  }
}

Ferramenta	Arquivo de configuração
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json`
Cursor	`.cursor/mcp.json` ou `~/.cursor/mcp.json`
Windsurf	`~/.windsurf/mcp.json`
Cline	Configurações do VS Code ou `.cline/mcp.json`

O JSON acima é idêntico para esses quatro clientes; apenas o caminho do arquivo muda. Claude Code e Codex não estão nesta tabela — eles gerenciam sua própria configuração por meio dos comandos CLI mostrados acima.

Remoto (sem instalação)

Use o endpoint hospedado em mcp.frihet.io — zero dependências locais, executa em Cloudflare Workers.

Com chave de API:

{
  "mcpServers": {
    "frihet": {
      "type": "streamable-http",
      "url": "https://mcp.frihet.io/mcp",
      "headers": {
        "Authorization": "Bearer fri_your_key_here"
      }
    }
  }
}

Com OAuth 2.0 + PKCE (login baseado em navegador, sem necessidade de chave de API):

Clientes que suportam OAuth (Claude Desktop, Smithery, etc.) podem conectar diretamente a https://mcp.frihet.io/mcp e autenticar via navegador. O servidor implementa o fluxo completo de código de autorização OAuth 2.1 com PKCE.

Obtenha sua chave de API

Entre em app.frihet.io
Vá para Configurações > API
Clique em Criar chave de API
Copie a chave (começa com fri_) — ela é mostrada apenas uma vez

O que você pode fazer

Converse com seu ERP. Estes são prompts reais, não texto de marketing.

Faturamento

"Show me all unpaid invoices"
"Create an invoice for Acme SL with 10h of consulting at 95/hour"
"Mark invoice abc123 as paid"
"How much has ClientName been invoiced this year?"

Despesas

"Log a 59.99 EUR expense for Adobe Creative Cloud, category: software, tax-deductible"
"List all expenses from January"
"What did I spend on travel last quarter?"

Clientes

"Add a new client: TechStart SL, NIF B12345678, email admin@techstart.es"
"Show me all my clients"
"Update ClientName's address to Calle Mayor 1, Madrid 28001"

CRM

"Add a contact to Acme SL: Ana Garcia, CTO, ana@acme.es"
"Log a call with TechStart: discussed Q2 proposal, they're interested in upgrade"
"Add a note to ClientName: prefers invoices in English, payment NET 30"
"Show me all activities for Acme SL"

Orçamentos

"Create a quote for Design Studio: logo design (2000 EUR) + brand guidelines (3500 EUR)"
"Show me all pending quotes"

Webhooks

"Set up a webhook to notify https://my-app.com/hook when invoices are paid"
"List all my active webhooks"

O que esperar

Este MCP é uma interface de dados estruturados — você descreve o que deseja em linguagem natural, e a IA cria, consulta ou modifica registros de negócios no Frihet. A maioria das 158 operações canônicas são operações CRUD sobre a API REST; o restante são resumos somente leitura e ações fiscais/e-invoice. Nomes de alias e descoberta são contados separadamente.

Funciona muito bem:

"Create an invoice for TechStart SL, 40h consulting at 75 EUR/h"   --> creates the invoice
"Show unpaid invoices over 1,000 EUR"                               --> queries and filters
"Log a 120 EUR expense for the Madrid train, category: travel"      --> records the expense
"Update client Acme's email to billing@acme.es"                     --> modifies the record

Não faz:

OCR ou digitalização de PDF — você não pode enviar uma imagem de fatura e esperar que ela seja lida
Upload de arquivos ou manipulação de anexos
Processamento de imagens de qualquer tipo

Se você precisar digitalizar faturas ou recibos em papel, extraia os dados primeiro (por exemplo, Claude Vision API, um serviço OCR dedicado ou entrada manual) e então use o MCP para criar o registro:

1. Scan/photograph the invoice
2. Use Claude Vision: "Read this invoice image and extract the vendor, items, amounts, and dates"
3. Then: "Create an expense in Frihet for [extracted data]"

Operações do catálogo (158)

Faturas (12)

Ferramenta	O que faz
`list_invoices`	Lista faturas com paginação
`get_invoice`	Obtém detalhes completos da fatura por ID
`create_invoice`	Cria uma nova fatura com itens de linha
`update_invoice`	Atualiza qualquer campo da fatura
`delete_invoice`	Exclui uma fatura rascunho; uma enviada/paga é cancelada, não destruída (`confirm=true` obrigatório)
`search_invoices`	Encontra faturas por nome do cliente, data ou status
`send_invoice`	Envia fatura por e-mail ao cliente (anexo PDF) — alcança terceiros, `confirm=true` obrigatório
`mark_invoice_paid`	Marca uma fatura como paga com data de pagamento opcional
`get_invoice_pdf`	Obtém bytes do PDF da fatura limitados como base64
`get_invoice_einvoice`	Obtém bytes do XML ou PDF Factur-X limitados para uma fatura
`create_credit_note`	Cria uma nota de crédito vinculada a uma fatura existente
`apply_late_fee`	Aplica uma taxa de atraso a uma fatura vencida

Despesas (5)

Ferramenta	O que faz
`list_expenses`	Lista despesas com paginação
`get_expense`	Obtém detalhes da despesa
`create_expense`	Registra uma nova despesa
`update_expense`	Modifica uma despesa
`delete_expense`	Exclui uma despesa

Clientes (5)

Ferramenta	O que faz
`list_clients`	Lista todos os clientes
`get_client`	Obtém detalhes do cliente
`create_client`	Registra um novo cliente
`update_client`	Atualiza informações do cliente
`delete_client`	Remove um cliente

CRM: Contatos (3)

Ferramenta	O que faz
`list_client_contacts`	Lista todos os contatos de um cliente
`create_client_contact`	Adiciona uma pessoa de contato a um cliente
`delete_client_contact`	Remove um contato de um cliente

CRM: Atividades (2)

Ferramenta	O que faz
`list_client_activities`	Lista atividades de CRM (chamadas, e-mails, reuniões, tarefas)
`log_client_activity`	Registra uma chamada, e-mail, reunião ou tarefa contra um cliente

CRM: Notas (3)

Ferramenta	O que faz
`list_client_notes`	Lista todas as notas de um cliente
`create_client_note`	Adiciona uma nota de texto livre a um cliente
`delete_client_note`	Remove uma nota de um cliente

Produtos (5)

Ferramenta	O que faz
`list_products`	Lista produtos e serviços
`get_product`	Obtém detalhes do produto
`create_product`	Adiciona um produto ou serviço
`update_product`	Atualiza preços ou detalhes
`delete_product`	Remove um produto

Orçamentos (6)

Ferramenta	O que faz
`list_quotes`	Listar todas as cotações
`get_quote`	Obter detalhes da cotação
`create_quote`	Criar um rascunho de nova cotação
`update_quote`	Modificar uma cotação
`delete_quote`	Excluir apenas um rascunho limpo, sem entrega, resposta, anexo ou evidência de conversão; recusar rascunhos protegidos; cancelar não-rascunhos (`confirm=true` obrigatório)
`send_quote`	Enviar cotação por e-mail ao cliente para aceitação

Webhooks (6)

Ferramenta	O que faz
`list_webhooks`	Listar webhooks configurados
`get_webhook`	Obter detalhes do webhook
`create_webhook`	Registrar um novo endpoint de webhook
`update_webhook`	Modificar eventos ou URL
`delete_webhook`	Remover um webhook
`test_webhook`	Enviar um payload de teste para um endpoint de webhook configurado

Inteligência (4)

Ferramenta	O que faz
`get_business_context`	Snapshot completo: perfil, plano, atividade recente, principais clientes, mês atual
`get_monthly_summary`	P&L mensal: receita, despesas, lucro, obrigação tributária, principais clientes por receita
`get_quarterly_taxes`	Preparação fiscal trimestral: campos do Modelo 303/130, coletado vs. dedutível, obrigação
`duplicate_invoice`	Clonar uma fatura para cobrança recorrente (copia itens/cliente/impostos, inicia como rascunho)

Faturamento Eletrônico (10)

Ferramenta	O que faz
`send_einvoice`	Enviar uma fatura em 11 formatos (XRechnung, Factur-X, FatturaPA, PEPPOL, Facturae, UBL, CII) via e-mail / Chorus Pro / SDI / PEPPOL / download
`get_einvoice_status`	Consultar o status da execução do workflow Hatchet até sucesso/falha — retorna ackId, URL do XML, URL do PDF/A-3
`validate_einvoice_xml`	Validar XML bruto contra o schema do formato + regras schematron (KOSIT / Mustang / XSD / Schematron)
`export_datev`	Exportar dados contábeis como DATEV EXTF (Buchungsstapel / Debitoren / Kreditoren) em codificação CP1252
`einvoice_export`	Exportar dados de fatura eletrônica em formatos legíveis por máquina (JSON/XML) para arquivamento ou integração
`face_submit`	Enviar fatura para o FACe (plataforma espanhola de faturamento eletrônico B2G)
`face_status`	Consultar o status de envio do FACe para uma fatura enviada
`ticketbai_submit`	Enviar registro fiscal TicketBAI para a autoridade tributária do País Basco (Hacienda)
`ticketbai_status`	Consultar o status de envio do TicketBAI na autoridade tributária basca
`ksef_submit`	NOT_DEPLOYED — Enviar fatura para o KSeF (Polônia) — stub: o transporte está pronto na infraestrutura do Frihet-ERP, mas ainda não exposto como endpoint ativo (produção condicionada ao certificado KSeF); retorna um erro rotulado como "indisponível" até ser ativado

Controle de Horas (6)

Ferramenta	O que faz
`list_time_entries`	Listar lançamentos de horas com filtro por usuário, projeto, intervalo de datas, status de faturamento
`get_time_entry`	Obter detalhes completos de um único lançamento de horas por ID
`create_time_entry`	Registrar horas para um projeto (flag de faturamento, descrição, data)
`update_time_entry`	Atualizar qualquer campo em um lançamento de horas existente (semântica PATCH)
`delete_time_entry`	Exclusão lógica de um lançamento de horas (confirm=true obrigatório)
`get_time_summary`	Agregar horas totais/faturáveis/não faturáveis para um período, com groupBy opcional (usuário/projeto/dia)

Faturas Recorrentes (8)

Ferramenta	O que faz
`list_recurring_invoices`	Listar todos os modelos de fatura recorrente (filtrar por ativo/pausado)
`get_recurring_invoice`	Obter detalhes completos de um modelo recorrente por ID
`create_recurring_invoice`	Criar um novo modelo de fatura recorrente (diário/semanal/mensal/trimestral/anual)
`update_recurring_invoice`	Atualizar campos do modelo — afeta apenas faturas futuras geradas
`pause_recurring_invoice`	Pausar um modelo ativo — nenhuma fatura é gerada enquanto pausado
`resume_recurring_invoice`	Retomar um modelo pausado — próxima fatura no próximo ciclo agendado
`delete_recurring_invoice`	Excluir permanentemente um modelo (confirm=true obrigatório)
`run_recurring_now`	Acionar manualmente a geração imediata da próxima instância de fatura

Gestão de Equipe (4)

Ferramenta	O que faz
`list_team_members`	Listar membros ativos + convites pendentes (proprietário excluído)
`invite_team_member`	Convidar um novo membro por e-mail com função (admin/editor/contador/visualizador)
`update_team_member_role`	Alterar a função de um membro existente (admin/editor/contador/visualizador)
`remove_team_member`	Remover um membro do workspace (confirm=true obrigatório)

Gestoria — Contadores (5)

Ferramenta	O que faz
`gestoria_message_send`	Enviar uma mensagem em um thread contextual (documentRequest / filingItem / obligation)
`gestoria_messages_list`	Listar mensagens em um thread, mais recentes primeiro; paginar para trás com `before`
`gestoria_template_create`	Criar um modelo reutilizável de solicitação de documentos com variáveis + offset de data de vencimento
`gestoria_template_bulk_send`	Envio em massa de um modelo para até 500 workspaces de clientes em uma única chamada
`gestoria_aging_consolidated`	Relatório de envelhecimento de contas a receber entre clientes (faixas, detalhamento por workspace, maiores vencidos)

Auditoria GL (3)

Ferramenta	O que faz
`frihet_gl_entry_approve`	Aprovar um lançamento contábil GL (somente gestor/admin — ÁREA DE CONFIANÇA)
`frihet_gl_entry_reject`	Rejeitar um lançamento GL com motivo obrigatório (ÁREA DE CONFIANÇA)
`frihet_gl_entry_audit_log`	Recuperar trilha de auditoria completa para um lançamento GL

Domínio do Portal White-label (3)

Ferramenta	O que faz
`frihet_portal_domain_add`	Adicionar um domínio personalizado ao portal do cliente (retorna registros DNS CNAME)
`frihet_portal_domain_verify`	Verificar propagação de DNS para um domínio de portal personalizado
`frihet_portal_domain_remove`	Remover um domínio de portal personalizado (reverte para o subdomínio padrão do Frihet)

Self-onboard & VIES (2)

Ferramenta	O que faz
`frihet_portal_onboard_link_generate`	Gerar um link de self-onboard com tempo limitado para um cliente potencial
`frihet_tax_id_vies_lookup`	Validar um número de IVA da UE (CIF intracomunitário) via VIES

IGIC — Imposto Indireto das Ilhas Canárias (4)

Ferramenta	O que faz
`frihet_modelo_415_summary`	M415 operações anuais >€3.005 (equivalente canário do M347) — não implantado, retorna `NOT_DEPLOYED`
`frihet_modelo_425_summary`	M425 resumo anual de IGIC para empresas das Ilhas Canárias — não implantado, retorna `NOT_DEPLOYED`
`frihet_modelo_418_summary`	M418 declaração mensal individual de IGIC, regime especial do grupo de entidades — não implantado, retorna `NOT_DEPLOYED`
`frihet_aiem_calculate`	Cálculo de AIEM (Arbitrio Importación) para Canárias — não implantado, retorna `NOT_DEPLOYED`

Impuesto sobre Sociedades — Imposto Corporativo (2)

Ferramenta	O que faz
`frihet_modelo_200_summary`	Declaração anual de IS do Modelo 200 — não implantado, retorna `NOT_DEPLOYED`
`frihet_modelo_202_summary`	Pagamentos por conta do Modelo 202 (1P/2P/3P) — não implantado, retorna `NOT_DEPLOYED`

Regras de Categorização Bancária (2)

Ferramenta	O que faz
`frihet_bank_rules_list`	Listar todas as regras de autocategorização bancária (condições + ações + status)
`frihet_bank_rule_create`	Criar uma nova regra para categorizar automaticamente transações por descrição, valor, contraparte

Depósitos (7)

Ferramenta	O que faz
`list_deposits`	Listar depósitos com paginação
`get_deposit`	Obter detalhes do depósito por ID
`create_deposit`	Registrar um novo depósito de cliente
`update_deposit`	Atualizar campos do depósito
`delete_deposit`	Excluir um depósito (confirm=true obrigatório)
`apply_deposit`	Aplicar um saldo de depósito contra uma fatura
`refund_deposit`	Emitir um reembolso para um depósito

Fornecedores (5)

Ferramenta	O que faz
`list_vendors`	Listar todos os fornecedores
`get_vendor`	Obter detalhes do fornecedor
`create_vendor`	Adicionar um novo fornecedor
`update_vendor`	Atualizar informações do fornecedor
`delete_vendor`	Remover um fornecedor

Banco (5)

Ferramenta	O que faz
`list_bank_accounts`	Listar contas bancárias conectadas
`get_bank_account`	Obter detalhes de uma conta bancária
`list_transactions`	Listar transações bancárias com filtros
`categorize_transaction`	Atribuir uma categoria e tipo de despesa/receita a uma transação
`match_transaction_to_invoice`	Vincular uma transação bancária a uma fatura existente

Fiscal — Modelos Tributários Espanhóis (7)

Ferramenta	O que faz
`get_modelo_303_summary`	Declaração trimestral de IVA (Modelo 303) — coletado vs. dedutível, valor líquido a pagar
`get_modelo_130_summary`	Pagamento trimestral de IRPF para autônomos (Modelo 130)
`get_modelo_390_summary`	Resumo anual de IVA (Modelo 390)
`get_modelo_180_summary`	Resumo anual de retenções para aluguéis (Modelo 180) — não implantado, retorna `NOT_DEPLOYED`
`get_modelo_347_summary`	Transações anuais com terceiros >€3.005 (Modelo 347)
`verifactu_status`	Obter status de envio VeriFactu para um registro fiscal
`verifactu_resubmit`	Reenviar um registro fiscal VeriFactu rejeitado
`ticketbai_status`	Consultar status de envio do TicketBAI — referência cruzada de Faturamento Eletrônico (10); NÃO contado para os 7 desta seção

Aluguéis de Temporada / Stay (5)

Ferramenta	O que faz
`list_reservations`	Listar reservas de aluguel com filtros
`get_reservation`	Obter detalhes da reserva
`create_reservation`	Criar uma nova reserva
`list_properties`	Listar todas as propriedades para aluguel
`sync_channel`	Acionar sincronização de canal OTA (Airbnb, Booking.com, etc.)

PDV — Ponto de Venda (4)

Ferramenta	O que faz
`list_terminals`	Listar terminais PDV registrados
`get_sale`	Obter detalhes de uma transação de venda no PDV
`list_sales`	Listar vendas no PDV com paginação
`refund_sale`	Emitir um reembolso para uma venda no PDV

Cozinha / Restaurante (6)

Ferramenta	O que faz
`list_kitchen_tickets`	Listar tickets de pedidos da cozinha para o painel ao vivo, filtrados por status ou estação
`get_kitchen_ticket`	Obter um único ticket de cozinha por ID com todos os itens e seus status individuais
`update_kitchen_ticket`	Avançar o status de um ticket (na fila → preparando → pronto → servido) ou reatribuí-lo a outra estação
`list_kitchen_stations`	Listar todas as estações da cozinha com id, nome e status ativo
`list_menu_items`	Listar o catálogo do menu da cozinha com busca de texto livre e filtro ativo/inativo
`kitchen_flow_summary`	Detecção de estação lenta: agregar tickets abertos por estação e sinalizar o gargalo

RH — Recursos Humanos (9)

Ferramenta	O que faz
`leave_request_create`	Criar uma solicitação de afastamento (férias, licença médica, pessoal)
`leave_approve`	Aprovar uma solicitação de afastamento pendente
`leave_reject`	Rejeitar uma solicitação de afastamento com um motivo
`leave_cancel`	Cancelar uma solicitação de afastamento aprovada ou pendente
`leave_list`	Listar solicitações de afastamento com filtros (usuário, status, intervalo de datas)
`attendance_clock_in`	Registrar entrada (clock-in) de um funcionário
`attendance_clock_out`	Registrar saída (clock-out) de um funcionário
`overtime_report`	Ler horas extras diárias/semanais, agregar minutos/horas e alertas de conformidade calculados sobre os registros YYYY ou YYYY-MM selecionados
`anomaly_list`	Listar anomalias de presença (pontos ausentes, horas extras excessivas)

Folha de Pagamento (2)

Ferramenta	O que faz
`payroll_export`	Ler dados normalizados de funcionários prontos para folha de pagamento; o valor do formato é um rótulo de destino ecoado, não um arquivo gerado
`payroll_checklist`	Listar funcionários pagáveis com prontidão de perfil de folha, campos ausentes e estado de revisão mensal

Onboarding (2)

Ferramenta	O que faz
`onboarding_status`	Obter status de conclusão do onboarding para o workspace atual
`onboarding_persona_set`	Definir ou atualizar a persona de negócio (freelancer, PME, gestoría, etc.)

Permissões (2)

Ferramenta	O que faz
`permissions_matrix`	Obter o snapshot documentado do modelo RBAC (não é uma garantia de autorização em tempo de execução)
`permissions_me`	Comparar campos do modelo RBAC com escopos reais de chaves de API e negações de escopo conhecidas (não exaustivo)

Fechamento de Período (3)

Ferramenta	O que faz
`period_close_status`	Obter o intervalo do ano fiscal YYYY atual ou selecionado, estado aberto/fechado e detalhes de fechamento anuláveis
`period_close`	Fechar um período contábil (somente gestor/admin — ÁREA DE CONFIANÇA)
`period_reopen`	Reabrir um período fechado com um motivo obrigatório (ÁREA DE CONFIANÇA)

Todas as operações canônicas (e seus aliases) retornam saída estruturada via outputSchema — JSON tipado, não texto bruto. As formas de resposta de listas seguem sua família de API; nem todo endpoint de lista é paginado.

Verdade sobre capacidade e efeitos colaterais

Nas superfícies MCP completas, cada entrada de tools/list inclui _meta["io.frihet/capability"]:

registered significa que o nome e o handler existem nesta compilação do servidor;
callability é api_dependent (o handler chama a API; implantação, habilitação do workspace e autorização ainda decidem), runtime_checked (o handler distingue explicitamente um backend ausente de dados vazios), deferred, unavailable ou local — nunca uma alegação incondicional de "disponível";
writesFrihet, externalInteraction e externalSideEffects distinguem mudanças de estado e chamadas a entidades/provedores externos;
As anotações de ação MCP permanecem a fonte padrão para dicas de somente leitura, destrutivas, idempotentes e de mundo aberto.

O host ChatGPT/OpenAI é uma superfície revisada separadamente: exatamente 33 operações de negócio com descrições completas, 0 meta-ferramentas de descoberta, 0 prompts e 0 recursos. Suas 17 leituras e 16 gravações são deliberadamente restritas, e todas as gravações exigem literalmente confirm=true. Dez gravações podem entregar eventos de negócio completos a endpoints ativos previamente configurados pelo proprietário do workspace; a administração de webhooks em si permanece excluída. Entrega direta de e-mail, o resumo mensal legado, PDFs brutos de faturas, transições de ciclo de vida de faturas, atualização de um orçamento existente, arquivamento regulado, exclusão de registros de clientes pais, exclusão de despesas com seus arquivos vinculados, exclusão de produtos e exclusão de fornecedores também são excluídos. Esta superfície não deve ser inferida do catálogo completo.

Recursos

Contexto que a IA pode ler para tomar decisões mais inteligentes.

O pacote local serve 11 recursos: 7 referências estáticas mais 4 recursos de workspace com suporte de API. O Worker hospedado serve os 7 recursos estáticos. O host revisado pela OpenAI serve 0 recursos.

Estáticos (dados de referência, sem chamadas de API):

Recurso	URI	O que fornece
Esquema da API	`frihet://api/schema`	Resumo OpenAPI: endpoints, autenticação, limites de taxa, paginação, códigos de erro
Alíquotas de Impostos	`frihet://tax/rates`	Alíquotas de impostos por zona fiscal espanhola: IVA, IGIC, IPSI, reverse charge da UE, IRPF
Calendário Fiscal	`frihet://tax/calendar`	Prazos de declaração trimestrais e anuais para os modelos fiscais espanhóis listados
Categorias de Despesas	`frihet://config/expense-categories`	8 categorias com regras de dedutibilidade, tratamento de IVA, amortização
Status de Faturas	`frihet://config/invoice-statuses`	Fluxo de status (rascunho > enviada > paga/vencida > cancelada), regras de transição, eventos de webhook
Moedas	`frihet://config/currencies`	40 moedas suportadas com códigos ISO, símbolos, casas decimais, formatação de localidade
Países	`frihet://config/countries`	61 países suportados com zonas fiscais, alíquotas de impostos padrão, moedas, prefixos de faturas

Dinâmicos (dados ao vivo da sua conta):

Recurso	URI	O que fornece
Perfil do Negócio	`frihet://business-profile`	Suas informações de negócio, plano, padrões, atividade recente, principais clientes
Snapshot Mensal	`frihet://monthly-snapshot`	P&L do mês atual, receita, despesas, obrigação tributária
Faturas Vencidas	`frihet://overdue-invoices`	Todas as faturas com data de vencimento passada (até 100)
Limites do Plano	`frihet://status/plan-limits`	Nível do plano ao vivo, contadores de uso, faturas/mês, limites de taxa da API

Prompts (10)

Fluxos de trabalho pré-construídos que a IA pode executar como operações guiadas em várias etapas.

Prompt	O que faz	Argumentos
`monthly-close`	Fechar o mês: revisar faturas não pagas, categorizar despesas, verificar obrigações fiscais, gerar resumo	`month?` (AAAA-MM)
`onboard-client`	Configurar um novo cliente com alíquotas de impostos corretas por localização, opcionalmente criar um orçamento de boas-vindas	`clientName`, `country?`, `region?`
`quarterly-tax-prep`	Preparar declaração fiscal trimestral: calcular IVA/IGIC, identificar dedutíveis, pré-visualizar Modelo 303/130/420	`quarter?`, `fiscalZone?`
`overdue-followup`	Encontrar faturas vencidas, redigir mensagens de acompanhamento, sugerir lembretes de pagamento	--
`new-client-invoice`	Criar um cliente + primeira fatura em um único fluxo de trabalho com consulta de alíquota de imposto	`clientName`, `country?`
`expense-report`	Gerar relatório de despesas agrupado por categoria com totais dedutíveis	`month?` (AAAA-MM)
`year-end-close`	Fechamento anual completo: revisão trimestral, faturas pendentes, despesas não categorizadas, checklist de fim de ano	`year` (AAAA)
`cash-flow-forecast`	Projetar fluxo de caixa para os próximos meses: receita recorrente, despesas, contas a receber vencidas, prazos fiscais	`months?` (padrão: 3)
`invoice-aging-review`	Análise de envelhecimento de contas a receber: agrupar faturas não pagas por faixa (0-30/31-60/61-90/90+ dias), principais devedores, ações de cobrança	--
`expense-batch`	Processar despesas em lote: categorizar, aplicar alíquotas de impostos, sinalizar recibos ausentes	`fiscalZone?`

Como funciona

graph LR
    AI["Your AI assistant"]
    MCP["frihet-mcp"]
    API["api.frihet.io"]
    DB["Frihet ERP"]

    AI -- "create_invoice()" --> MCP
    MCP -- "POST /v1/invoices" --> API
    API --> DB
    DB -- "201 + invoice data" --> API
    API -- "structured JSON" --> MCP
    MCP -- "typed response + suggestions" --> AI

    style AI fill:#09090b,stroke:#4ade80,color:#fafafa
    style MCP fill:#09090b,stroke:#fafafa,color:#fafafa
    style API fill:#09090b,stroke:#3f3f46,color:#a1a1aa
    style DB fill:#09090b,stroke:#3f3f46,color:#a1a1aa

O servidor traduz chamadas de ferramentas em solicitações de API REST. Ele lida com autenticação, limite de taxa (repetição automática com backoff em 429), paginação e mapeamento de erros.

Dois transportes:

stdio (local) -- npx @frihet/mcp-server com FRIHET_API_KEY
Streamable HTTP (remoto) -- https://mcp.frihet.io/mcp com token Bearer ou OAuth 2.0+PKCE

Variáveis de ambiente

Variável	Obrigatória	Padrão
`FRIHET_API_KEY`	Sim (stdio)	--
`FRIHET_API_URL`	Não	`https://api.frihet.io/v1`
`FRIHET_TOOL_MODE`	Não	`full`

Exposição de ferramentas: profundidade sob demanda

O diferencial do Frihet é a profundidade — cobertura fiscal completa ES/UE mais conformidade nativa (VeriFactu, TicketBAI, Facturae/FACe; KSeF Polônia infra-pronta, ativação pendente), bancos, CRM, RH/folha de pagamento, stay/PMS e POS. Mas uma lista plana de todas as ferramentas, carregada no contexto de um agente antecipadamente, é o problema de apodrecimento de contexto de 2026: ela ocupa espaço da tarefa e degrada a seleção de ferramentas antes que qualquer trabalho comece.

FRIHET_TOOL_MODE permite que você escolha como essa profundidade é exposta.

Modo	Comportamento
`full` (padrão)	Ferramentas canônicas e aliases fiscais são expostos com descrições e esquemas completos. Descritores públicos adicionam verdade conservadora de chamabilidade e efeitos colaterais; nomes de operações, esquemas e handlers permanecem inalterados.
`grouped`	Divulgação progressiva. A descrição de cada ferramenta é reduzida a um `[group] summary — full schema via describe_tool('name')` de uma linha, e três ferramentas leves de descoberta são adicionadas. O agente carrega profundidade apenas para as ferramentas que realmente precisa.

No modo grouped, nomes de operações, esquemas de entrada e handlers permanecem inalterados. Descritores também expõem a mesma verdade conservadora de capacidade e ação que o perfil completo. A descoberta flui por três meta-ferramentas:

list_tool_groups() — o mapa de domínio (faturamento, despesas, fiscal/conformidade, bancos, CRM, RH/folha de pagamento, stay/PMS, POS, inteligência, produtos, plataforma) com uma descrição de uma linha e contagem de ferramentas para cada um.
search_tools(query) — busca de texto livre em nome da ferramenta, título, resumo e grupo; retorna ferramentas correspondentes com seu grupo, resumo, sinalizador somente leitura e campos de entrada. Filtro opcional group e limit.
describe_tool(name) — a descrição original completa e campos de entrada para uma ferramenta, sob demanda, antes de chamá-la.

// claude_desktop_config.json — opt in to grouped mode
{
  "mcpServers": {
    "frihet": {
      "command": "npx",
      "args": ["@frihet/mcp-server"],
      "env": {
        "FRIHET_API_KEY": "fri_...",
        "FRIHET_TOOL_MODE": "grouped"
      }
    }
  }
}

A exposição agrupada muda a densidade da descrição, não o comportamento da operação. O perfil revisado pela OpenAI com versão é composto separadamente e permanece com acesso independente.

Limites da API

Limite	Valor
Solicitações por minuto	100 por chave de API
Resultados por página	100 máx (50 padrão)
Corpo da solicitação	1 MB máx
Payload de webhook	100 KB máx
Webhooks por conta	20 máx

O limite de taxa é tratado automaticamente com backoff exponencial.

Skill do Claude Code

Além das ferramentas MCP brutas, este repositório inclui uma skill do Claude Code que adiciona contexto de negócio: regras fiscais espanholas, receitas de fluxo de trabalho, relatórios financeiros e comandos em linguagem natural.

Instalar a skill

git clone https://github.com/Frihet-io/frihet-mcp.git
ln -s "$(pwd)/frihet-mcp/skill" ~/.claude/skills/frihet

Ou com o instalador universal:

npx skills add Frihet-io/frihet-mcp

Comandos

Comando	O que faz
`/frihet status`	Visão geral da conta, atividade recente, pagamentos pendentes
`/frihet invoice`	Criar, listar, pesquisar faturas
`/frihet expense`	Registrar e consultar despesas
`/frihet clients`	Gerenciar banco de dados de clientes
`/frihet quote`	Criar e gerenciar orçamentos
`/frihet report`	Resumos financeiros (P&L, trimestral, vencidos)
`/frihet webhooks`	Configurar gatilhos de automação
`/frihet setup`	Configuração guiada e teste de conexão

A skill conhece alíquotas de IVA, retenção de IRPF, preparação do Modelo 303, regras de dedutibilidade de despesas e conformidade VeriFactu.

Documentação completa: docs.frihet.io/desarrolladores/skill-claude-code

Desenvolvimento

git clone https://github.com/Frihet-io/frihet-mcp.git
cd frihet-mcp
npm install
npm run build

Execute localmente:

FRIHET_API_KEY=fri_xxx node dist/index.js

Teste com o Inspetor MCP:

npx @modelcontextprotocol/inspector node dist/index.js

Contribuindo

Contribuições são bem-vindas. Por favor, abra uma issue primeiro para discutir o que você gostaria de mudar.

git clone https://github.com/Frihet-io/frihet-mcp.git
cd frihet-mcp
npm install
npm run build   # must pass before submitting

Limitações atuais

Sem OCR ou upload de arquivos -- o MCP trabalha com dados estruturados, não imagens ou PDFs.
Empresa única -- uma chave de API mapeia para um workspace do Frihet.
Conta Frihet necessária -- você precisa de uma conta ativa em app.frihet.io e uma chave de API (começa com fri_).

Ecossistema

Pacote	O que é
`@frihet/mcp-server`	Este servidor MCP (158 operações canônicas + 5 nomes de alias; 11 recursos locais; 10 prompts)
`@frihet/sdk`	SDK TypeScript (`frihet.invoices.create()`)
`frihet`	CLI (`frihet invoices list --status overdue`)
`n8n-nodes-frihet`	Nó comunitário n8n para automação de fluxos de trabalho
API REST	OpenAPI 3.1 em `api.frihet.io/v1`
MCP Remoto	Endpoint hospedado em Cloudflare Workers (zero instalação)
Webhooks	Eventos em tempo real com HMAC-SHA256

Licença

MIT. Veja LICENSE.

Construído por Frihet.