🏦 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

Total: 42 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

O OMIE não tem um campo que marque o cadastro como fornecedor: o que identifica um fornecedor é a tag Fornecedor. incluir_fornecedor e upsert_fornecedor aplicam essa tag sempre, e alterar_fornecedor a mantém quando recebe tags, para que o cadastro continue aparecendo em listar_fornecedores.

Contas a Pagar

Contas a Receber

Lançamentos Bancários

Contas Correntes

Fluxo de Caixa

Categorias

Contas do DRE

Tipos de Documento

Bancos

🔗 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.