omie-finance-mcp

Um servidor MCP que expõe a API financeira do OMIE ERP como ferramentas para agentes de IA. Em vez de navegar pelo painel do OMIE ou montar chamadas HTTP manualmente, um assistente (Claude, ou qualquer outro cliente compatível com MCP) passa a conseguir consultar títulos, lançar pagamentos/recebimentos, gerar boletos e PIX, e ler o fluxo de caixa — tudo a partir de um pedido em linguagem natural.

Exemplos do tipo de pedido que o assistente consegue resolver sozinho:

"Quais contas a pagar vencem essa semana?" "Gera um boleto pro título 4821 com vencimento pro dia 10" "Qual o saldo da conta corrente principal hoje?" "Cadastra a Fulana Ltda como fornecedora, CNPJ 12.345.678/0001-99"

Como o projeto é organizado

• client.py — cliente HTTP puro para a API do OMIE. Cada operação (listar_contas_pagar, gerar_pix, etc.) é um método nomeado, então dá pra usar essa classe fora do contexto do MCP também, se precisar.

• auth.py — só entra em jogo no modo servidor HTTP (ver abaixo): resolve qual credencial OMIE atende cada requisição.

• server.py — monta o servidor MCP (via FastMCP) e registra as ferramentas.

• tools/ — um arquivo por área do OMIE (contas a pagar, PIX, cadastros...), cada um só traduzindo argumentos da ferramenta para uma chamada do client.py.

Duas formas de rodar, dependendo do uso:

Related MCP server: AlphaVantage MCP Server

Requisitos

• Python 3.12 ou superior

• Uma app_key/app_secret do OMIE (Configurações → API → Aplicações, dentro do OMIE)

• Para o modo local: uv

• Para o modo servidor: Docker + Docker Compose

Modo local

Ideal quando é só você usando, com uma única conta OMIE.

Sem clonar nada, direto do GitHub:

OMIE_APP_KEY=sua_key OMIE_APP_SECRET=seu_secret \
  uvx --from git+https://github.com/denilsonpy/omie-finance-mcp omie-finance-mcp

Se preferir não repetir as credenciais toda vez, salve-as em ~/.config/omie-finance-mcp/.env:

mkdir -p ~/.config/omie-finance-mcp
printf 'OMIE_APP_KEY=sua_key\nOMIE_APP_SECRET=seu_secret\n' > ~/.config/omie-finance-mcp/.env

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

Clonando o repositório (útil se for mexer no código):

git clone https://github.com/denilsonpy/omie-finance-mcp
cd omie-finance-mcp
cp .env.example .env   # preencha OMIE_APP_KEY e OMIE_APP_SECRET
uv run omie-finance-mcp

Registrando no Claude Desktop

Edite o arquivo de configuração — macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Linux: ~/.config/Claude/claude_desktop_config.json:

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

No Windows via WSL, o Claude Desktop roda fora do Linux, então o jeito confiável é um script wrapper. Dentro do WSL:

mkdir -p ~/.config/omie-finance-mcp
printf 'OMIE_APP_KEY=sua_app_key\nOMIE_APP_SECRET=seu_app_secret\n' > ~/.config/omie-finance-mcp/.env

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

E em %APPDATA%\Claude\claude_desktop_config.json:

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

(troque SEU_USUARIO pelo valor de whoami dentro do WSL)

Modo servidor (Docker, multi-cliente)

Aqui a lógica muda: em vez de um processo por usuário com uma credencial fixa, sobe um único servidor HTTP que várias pessoas/clientes compartilham — e cada um usa a própria conta OMIE.

Isso só funciona porque a autenticação é por requisição: o servidor não guarda app_key/app_secret nenhum. Cada chamada MCP chega com HTTP Basic Auth (usuário = app_key, senha = app_secret), e é essa credencial — validada pelo próprio OMIE, não por um cadastro paralelo — que decide qual conta aquela chamada enxerga. Um cliente não tem como acessar dados de outro porque literalmente não tem a chave dele.

git clone https://github.com/denilsonpy/omie-finance-mcp
cd omie-finance-mcp
cp .env.example .env   # não preencha OMIE_APP_KEY/SECRET aqui, ver acima
docker compose up -d --build

Por padrão sobe em http://localhost:8020/mcp. docker compose down para; restart: unless-stopped no compose já garante que volta sozinho depois de um reboot.

Antes de expor isso na internet

Duas coisas que precisam estar certas:

1. TLS na frente. Basic Auth só ofusca em base64 — sem HTTPS, a credencial de qualquer cliente pode ser capturada em trânsito. Coloque um reverse proxy (Caddy, nginx) com certificado válido antes de aceitar tráfego público; dá pra conseguir HTTPS sem nem ter domínio próprio usando sslip.io. Numa rede fechada (VPN, LAN), Basic Auth sozinho já resolve.

2. MCP_ALLOWED_HOSTS. O SDK do MCP tem proteção contra DNS rebinding e, por padrão, só aceita requisições cujo Host seja localhost. Atrás de um domínio/IP público, declare esse hostname na variável (ver .env.example) — senão toda chamada externa recebe 421.

Cada cliente se conecta com a própria credencial

# gera o header a partir do app_key/app_secret do cliente
echo -n "APP_KEY_DO_CLIENTE:APP_SECRET_DO_CLIENTE" | base64

claude mcp add --transport http omie-finance-mcp https://seu-servidor/mcp \
  --header "Authorization: Basic <valor_gerado_acima>"

ou equivalente em .mcp.json / claude_desktop_config.json:

{
  "mcpServers": {
    "omie-finance-mcp": {
      "type": "http",
      "url": "https://seu-servidor/mcp",
      "headers": { "Authorization": "Basic <valor_gerado_acima>" }
    }
  }
}

Ferramentas disponíveis

54 ferramentas ao todo, agrupadas por área:

Cadastros

Contas a Pagar

Contas a Receber

Cobranças — Boleto e PIX

Movimento bancário

Visão financeira

Estrutura

omie-finance-mcp/
├── src/omie_finance_mcp/
│   ├── client.py
│   ├── auth.py
│   ├── server.py
│   └── tools/
│       ├── suppliers.py
│       ├── accounts_payable.py
│       ├── accounts_receivable.py
│       ├── bank_accounts.py
│       ├── bank_transactions.py
│       ├── receivable_boletos.py
│       ├── receivable_pix.py
│       ├── cash_flow.py
│       ├── financial_movements.py
│       └── finance_registries.py
├── Dockerfile
├── docker-compose.yml
├── .env.example
└── pyproject.toml

Licença

MIT — veja LICENSE.