omie-mcp

🏦 omie-mcp

Servidor MCP (Model Context Protocol) para integração com o ERP OMIE. Permite controlar suas finanças diretamente pelo Claude (ou qualquer cliente MCP), usando linguagem natural.

✨ O que você pode fazer

Converse com o Claude e peça coisas como:

• "Liste todas as contas a pagar em aberto do mês"
• "Registre o pagamento da fatura do fornecedor X"
• "Mostre o extrato bancário da conta corrente de março"
• "Qual o fluxo de caixa previsto vs realizado em fevereiro?"
• "Cadastre um novo fornecedor com CNPJ 12.345.678/0001-99"
• "Crie uma categoria de despesa para 'Assinaturas de Software' ligada ao DRE"
• "Qual o código do tipo de documento de boleto?"

---

🗂️ Módulos disponíveis

| Módulo | Ferramentas | |---|---| | Fornecedores | Listar, consultar, cadastrar e alterar fornecedores | | Contas a Pagar | Listar, consultar, incluir, lançar pagamento, cancelar e excluir | | Contas a Receber | Listar, consultar, incluir, lançar recebimento, cancelar e excluir | | Lançamentos Bancários | Listar, consultar, incluir e excluir transações em conta corrente | | Contas Correntes | Listar contas, consultar detalhes, extrato bancário por período e tipos de conta | | Fluxo de Caixa | Previsto vs realizado, resumo financeiro, títulos em aberto e pesquisa unificada | | Categorias | Listar, consultar, incluir e alterar categorias e grupos totalizadores | | Contas do DRE | Listar a estrutura do DRE e as contas vinculáveis a categorias | | Tipos de Documento | Pesquisar por descrição e consultar por código | | Bancos | Listar e consultar instituições financeiras e seus recursos de integração |

Total: 41 ferramentas MCP

---

📋 Pré-requisitos

• Python 3.12+
• uv instalado
• Credenciais de API do OMIE (app_key e app_secret)

Para obter as credenciais, acesse no OMIE: Configurações → API → Aplicações

---

🚀 Instalação e uso

Opção 1 — uvx direto do GitHub (sem instalar nada)

uvx --from git+https://github.com/lucassampsouza/omie-mcp omie-mcp

As credenciais podem ser passadas por variáveis de ambiente ou por um arquivo .env:

# Via variáveis de ambiente
OMIE_APP_KEY=sua_key OMIE_APP_SECRET=seu_secret \
  uvx --from git+https://github.com/lucassampsouza/omie-mcp omie-mcp

# Via arquivo de configuração global (recomendado para uso contínuo)
mkdir -p ~/.config/omie-mcp
echo "OMIE_APP_KEY=sua_key"     >> ~/.config/omie-mcp/.env
echo "OMIE_APP_SECRET=seu_secret" >> ~/.config/omie-mcp/.env

uvx --from git+https://github.com/lucassampsouza/omie-mcp omie-mcp

---

Opção 2 — Clone local com uv

git clone https://github.com/lucassampsouza/omie-mcp
cd omie-mcp

# Configure as credenciais
cp .env.example .env
# Edite o .env com sua app_key e app_secret

uv run omie-mcp

---

🖥️ Configuração no Claude Desktop

Linux / macOS

Edite o arquivo de configuração do Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "omie": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/lucassampsouza/omie-mcp",
        "omie-mcp"
      ],
      "env": {
        "OMIE_APP_KEY": "sua_app_key",
        "OMIE_APP_SECRET": "seu_app_secret"
      }
    }
  }
}

---

Windows com WSL

Como o Python roda dentro do WSL, a forma mais confiável é usar um script wrapper que carrega as credenciais.

1. Configure as credenciais dentro do WSL:

mkdir -p ~/.config/omie-mcp
cat > ~/.config/omie-mcp/.env << EOF
OMIE_APP_KEY=sua_app_key
OMIE_APP_SECRET=seu_app_secret
EOF

2. Crie o script wrapper em ~/omie-mcp-run.sh:

cat > ~/omie-mcp-run.sh << 'EOF'
#!/bin/bash
set -e
export $(grep -v '^#' ~/.config/omie-mcp/.env | xargs)
exec uvx --from git+https://github.com/lucassampsouza/omie-mcp omie-mcp
EOF
chmod +x ~/omie-mcp-run.sh

3. Edite %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "omie": {
      "command": "wsl",
      "args": ["/home/SEU_USUARIO/omie-mcp-run.sh"]
    }
  }
}

Substitua SEU_USUARIO pelo seu usuário no WSL (rode whoami no terminal WSL para confirmar).

---

🔧 Referência das ferramentas

Fornecedores

| Ferramenta | Descrição | |---|---| | listar_fornecedores | Lista fornecedores com filtros por nome ou CNPJ | | consultar_fornecedor | Consulta detalhes de um fornecedor pelo código ou CNPJ | | incluir_fornecedor | Cadastra um novo fornecedor | | alterar_fornecedor | Atualiza dados de um fornecedor existente |

Contas a Pagar

| Ferramenta | Descrição | |---|---| | listar_contas_pagar | Lista contas filtrando por status, período e fornecedor | | consultar_conta_pagar | Consulta detalhes de uma conta específica | | incluir_conta_pagar | Cria uma nova conta a pagar | | lancar_pagamento | Registra o pagamento (baixa) de uma conta | | cancelar_pagamento_conta_pagar | Estorna o pagamento de uma conta | | excluir_conta_pagar | Exclui uma conta a pagar em aberto |

Contas a Receber

| Ferramenta | Descrição | |---|---| | listar_contas_receber | Lista contas filtrando por status, período e cliente | | consultar_conta_receber | Consulta detalhes de uma conta específica | | incluir_conta_receber | Cria uma nova conta a receber | | lancar_recebimento | Registra o recebimento (baixa) de uma conta | | cancelar_recebimento | Estorna o recebimento de uma conta | | excluir_conta_receber | Exclui uma conta a receber em aberto |

Lançamentos Bancários

| Ferramenta | Descrição | |---|---| | listar_lancamentos_bancarios | Lista transações de conta corrente por período | | consultar_lancamento_bancario | Consulta detalhes de um lançamento | | incluir_lancamento_bancario | Cria lançamento manual (débito ou crédito) | | excluir_lancamento_bancario | Exclui um lançamento bancário |

Contas Correntes

| Ferramenta | Descrição | |---|---| | listar_contas_correntes | Lista todas as contas bancárias cadastradas no OMIE | | consultar_conta_corrente | Consulta detalhes de uma conta corrente específica | | consultar_extrato_bancario | Extrato completo de uma conta em um período | | listar_tipos_conta_corrente | Tipos aceitos no cadastro de conta corrente (CC, CP, CR, CX…) |

Fluxo de Caixa

| Ferramenta | Descrição | |---|---| | consultar_fluxo_caixa | Previsto vs realizado por categoria em um mês | | obter_resumo_financeiro | Resumo consolidado numa data de referência | | listar_titulos_em_aberto | Títulos não liquidados (a pagar ou a receber) | | pesquisar_lancamentos_financeiros | Pesquisa unificada (contas a pagar + a receber) |

Categorias

| Ferramenta | Descrição | |---|---| | listar_categorias | Lista o plano de categorias, com filtros por tipo (R/D) e descrição | | consultar_categoria | Consulta uma categoria pelo código, com a conta do DRE vinculada | | listar_grupos_categoria | Grupos totalizadores — os valores válidos para categoria_superior | | listar_tipos_categoria | Tipos de categoria — os valores válidos para tipo_categoria | | incluir_categoria | Cria uma categoria dentro de um grupo totalizador | | alterar_categoria | Altera ou inativa uma categoria existente | | incluir_grupo_categoria | Cria um grupo totalizador de receita ou despesa | | alterar_grupo_categoria | Altera a descrição/natureza de um grupo |

Contas do DRE

| Ferramenta | Descrição | |---|---| | listar_contas_dre | Estrutura do DRE; com apenas_vinculaveis traz só as contas aceitas por uma categoria |

Tipos de Documento

| Ferramenta | Descrição | |---|---| | listar_tipos_documento | Pesquisa por descrição (ignora acentos e maiúsculas) | | consultar_tipo_documento | Consulta um tipo pelo código exato (BOL, NF, ADI…) |

Bancos

| Ferramenta | Descrição | |---|---| | listar_bancos | Lista instituições financeiras, com filtro por nome e tipo | | consultar_banco | Detalhes de integração do banco (PIX, extrato, CNAB, boletos) |

---

🔗 Como os cadastros de apoio se encaixam

As categorias são a espinha dorsal da classificação financeira, e o OMIE valida os vínculos na inclusão. A ordem que funciona é:

listar_grupos_categoria   → escolhe categoria_superior (ex: 2.01)
listar_tipos_categoria    → escolhe tipo_categoria com cTipo compatível
                            (grupo 1.xx → R, grupo 2.xx → P)
listar_contas_dre         → escolhe codigo_dre entre as contas vinculáveis
                            (apenas_vinculaveis=True)
incluir_categoria         → cria a categoria já classificada no DRE

Categorias, tipos de documento, bancos e tipos de conta corrente são justamente os códigos consumidos ao lançar contas a pagar, contas a receber e lançamentos bancários — consulte-os antes de criar um lançamento em vez de adivinhar códigos.

Somente leitura: a API do OMIE não expõe inclusão, alteração nem exclusão para contas do DRE, tipos de documento, bancos e tipos de conta corrente — essas tabelas são mantidas pelo ERP. Categoria também não tem exclusão: use alterar_categoria com inativar=True.

Consumo redundante: o OMIE bloqueia por ~40 segundos a repetição de uma chamada idêntica (mesmo método e mesmos parâmetros), respondendo Consumo redundante detectado. Varie os filtros ou aguarde a janela.

---

📁 Estrutura do projeto

omie-mcp/
├── src/omie_mcp/
│   ├── client.py          # Cliente HTTP para a API do OMIE
│   ├── server.py          # Servidor MCP (FastMCP)
│   └── tools/
│       ├── fornecedores.py
│       ├── contas_pagar.py
│       ├── contas_receber.py
│       ├── lancamentos_cc.py
│       ├── contas_correntes.py
│       ├── fluxo_caixa.py
│       ├── categorias.py
│       ├── dre.py
│       ├── tipos_documento.py
│       └── bancos.py
├── .env.example           # Modelo de variáveis de ambiente
├── pyproject.toml
└── README.md

---

📄 Licença

MIT — veja o arquivo LICENSE para detalhes.