Aikount MCP

Contabilidade espanhola com IA: emita faturas, registre despesas por OCR, concilie o banco e prepare o Modelo 303 a partir do Claude, Cursor ou ChatGPT.

GitHub

Documentação

Aikount MCP — Contabilidade espanhola com IA para Claude, Cursor e ChatGPT

Servidor MCP de contabilidade para autônomos e PMEs na Espanha. Leve sua contabilidade para qualquer agente de IA: emita faturas, capture PDFs de despesas por OCR, concilie movimentações bancárias e prepare o Modelo 303 — tudo a partir do Claude, Cursor, ChatGPT ou qualquer cliente MCP.

Aikount é um SaaS de contabilidade agent-first: uma alternativa ao Holded pensada para que seja uma IA quem leve a contabilidade. Este repositório é o servidor MCP (Model Context Protocol) oficial que conecta seu agente de IA aos seus livros por meio da API REST pública da Aikount. A API é o produto; a interface web é o plano B para humanos.

Você é autônomo ou escritório de contabilidade e quer que um agente de IA leve sua contabilidade na Espanha? Comece em aikount.com e conecte seu agente com este servidor MCP.

O que você pode fazer? (ferramentas)

Ferramenta	O que faz
`whoami`	Verifica o token e retorna o tenant (empresa) ativo
`list_contacts` / `create_contact`	Clientes e fornecedores
`list_tax_types`	Tipos de IVA/IGIC/IPSI/IRPF e seus UUIDs para as linhas
`list_products`	Catálogo de produtos/serviços
`list_invoices` / `get_invoice`	Consultar faturas de venda
`create_invoice` / `issue_invoice`	Criar rascunho e emitir (atribui número legal)
`list_purchases` / `get_purchase`	Consultar despesas / faturas de compra
`ingest_purchase_pdf` / `get_ingest_job`	OCR de um PDF para uma despesa sem duplicatas
`list_treasuries`	Contas bancárias / Stripe / PayPal com saldo
`list_bank_movements`	Movimentações bancárias, com filtros
`reconciliation_board` / `reconcile_movement`	Conciliação bancária automática
`list_accounts` / `ledger` / `trial_balance`	Plano Geral de Contabilidade (PGC), razão e somas e saldos
`modelo_303_summary` / `modelo_303_csv`	IVA trimestral (Modelo 303)
`api_request`	Acesso a qualquer outro endpoint (ver OpenAPI)

Por que não existe create_purchase? Faturas de compra duplicadas corrompem os totais de despesas, o IVA suportado e a conciliação bancária. Por isso, as despesas só são adicionadas via ingest_purchase_pdf, que deduplica por identidade de fatura.

Instalação

Você precisa de uma API key da Aikount (escopo *, com prefixo agl_). Você a gera com o botão «Conectar agente» dentro do app web da Aikount — ele mostra as linhas export exatas.

Opção A — Hospedado, sem instalar nada (MCP remoto)

Conecte seu cliente ao endpoint hospedado com seu token no cabeçalho:

URL:    https://api.aikount.com/mcp        (streamable-HTTP)
Header: Authorization: Bearer agl_tu_token

É multi-tenant: cada requisição é autenticada com seu próprio token. Ideal para clientes que suportam MCP remoto. As mesmas ferramentas da versão local.

Opção B — Local (este pacote)

export AIKOUNT_TOKEN="agl_xxxxxxxxxxxxxxxxxxxxxxxx"
# opcional, por defecto producción:
# export AIKOUNT_API="https://api.aikount.com/api/v1"

Execute com uv (sem instalar nada):

uvx aikount-mcp

Ou com pip/pipx:

pipx install aikount-mcp   # o: pip install aikount-mcp
aikount-mcp

Claude Desktop / Claude Code

Adicione à sua configuração MCP (claude_desktop_config.json, ou .mcp.json no Claude Code):

{
  "mcpServers": {
    "aikount": {
      "command": "uvx",
      "args": ["aikount-mcp"],
      "env": { "AIKOUNT_TOKEN": "agl_xxxxxxxxxxxxxxxxxxxxxxxx" }
    }
  }
}

Cursor

Configurações → MCP → Add new server, com o mesmo command / args / env.

Casos de uso

«Emita uma fatura de 1.200 € para a ACME pela consultoria de maio.» O agente busca o contato, resolve o IVA e cria o rascunho; você confirma e ele emite.
«Adicione este PDF da Amazon Web Services como despesa.» OCR + inclusão deduplicada da despesa no Plano Geral de Contabilidade.
«Como está meu IVA do segundo trimestre?» Resumo do Modelo 303 na hora.
«Concilie as movimentações do banco com as faturas.» Conciliação bancária automática (autoconcilia com confiança ≥ 0,95).

Convenções

Dinheiro em euros decimais (unit_price: 1200.00), não em centavos. EUR salvo se currency disser outra coisa.
Datas ISO-8601 AAAA-MM-DD. IDs são UUIDs.
As linhas referenciam impostos por tax_type_id (UUID de list_tax_types), não por um código de texto. Omita para herdar o do contato/produto.
Os erros retornam como {"error": true, "status_code": ..., "detail": ..., "hint": ...} para que o modelo se autocorrija (reautenticação em 401, corrigir o corpo em 422).
O token tem escopo * — trate-o como uma senha. O isolamento por empresa (multi-tenant) é automático.

A especificação OpenAPI é a fonte da verdade para tudo o que este servidor não encapsula; acesse-a via api_request.

Perguntas frequentes (FAQ)

O que é o Aikount MCP?

É um servidor MCP (Model Context Protocol) que conecta agentes de IA como Claude, Cursor ou ChatGPT à sua contabilidade na Aikount, para que a IA possa emitir faturas, registrar despesas, conciliar o banco e preparar impostos (Modelo 303) usando o Plano Geral de Contabilidade espanhol.

Como conecto o Claude (ou Cursor/ChatGPT) à minha contabilidade?

Instale o servidor com uvx aikount-mcp, gere sua API key na Aikount com «Conectar agente» e adicione o bloco mcpServers à configuração do seu cliente MCP. Em segundos, seu agente pode ler e escrever nos seus livros.

É seguro? A Aikount guarda minhas credenciais bancárias?

Não. A conexão bancária é feita por meio de gateways PSD2 regulamentados (Ponto Connect, Salt Edge, GoCardless); a Aikount nunca armazena credenciais do banco. Os dados são hospedados na UE. O token da API é revogável e está isolado por empresa.

Serve para autônomos e PMEs na Espanha?

Sim. A Aikount é pensada para autônomos e PMEs espanholas e para os escritórios de contabilidade que os supervisionam, com suporte multiempresa e multimoeda, Plano Geral de Contabilidade e Veri*Factu. Não substitui seu contador: entrega o trabalho pronto para revisão e assinatura.

O que é o Modelo 303 e a IA pode prepará-lo?

O Modelo 303 é a autoliquidação trimestral do IVA na Espanha. O agente gera o resumo por trimestre (modelo_303_summary) e o detalhe por operação (modelo_303_csv) prontos para revisar e apresentar.

É uma alternativa ao Holded?

Sim. Onde o Holded é um conjunto por módulos, a Aikount é um agente de IA focado em fazer sua contabilidade, com preço por faixa de faturamento. Comparativo: aikount.com/alternativas-a-holded.

Sobre a Aikount

Aikount — contabilidade espanhola agent-first para autônomos, PMEs e escritórios de contabilidade. Recursos:

🌐 Web: aikount.com
🤖 Contabilidade com IA: aikount.com/contabilidad-con-ia
🏦 Conciliação bancária automática: aikount.com/conciliacion-bancaria-automatica
🧮 Calculadora de IVA trimestral (Modelo 303): aikount.com/calculadora-iva-trimestral
🆚 Alternativa ao Holded: aikount.com/alternativas-a-holded
📚 Documentação da API: api.aikount.com/docs
🧩 Contexto para agentes: aikount.com/llms.txt

Desenvolvimento

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest -q          # 23 tests, sin red (httpx MockTransport)

Os testes fixam cada ferramenta à rota real da API verificada contra a especificação OpenAPI em tempo real, para que as rotas não quebrem silenciosamente.

server.json é o manifesto deste pacote para o registro oficial de MCP.

Licença

MIT — ver LICENSE.