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): recusa requisição sem credencial e resolve, a cada chamada, qual credencial OMIE a atende.

• config.py — configuração lida do ambiente e dos .env.

• 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 a credencial de quem a fez, de uma destas duas formas:

Authorization: Basic base64("app_key:app_secret")

X-Omie-App-Key: <app_key>
X-Omie-App-Secret: <app_secret>

É 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. Requisição sem credencial recebe 401 com um corpo JSON explicando o que faltou, e não chega a entrar no servidor MCP.

A resolução acontece em cada chamada de ferramenta, a partir dos headers da requisição que a originou — não uma vez por sessão. É o que garante que duas chamadas na mesma sessão MCP, com credenciais diferentes, operem cada uma na sua conta (ver tests/test_http_session_hijack.py).

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. A credencial viaja em claro (o base64 do Basic só ofusca) — sem HTTPS, a chave 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), a credencial sozinha já resolve.

2. MCP_ALLOWED_HOSTS. O SDK do MCP tem proteção contra DNS rebinding, que depende de uma allowlist de Host. Vazio (o padrão) ela fica desligada — é o que um servidor acessado remotamente precisa, porque a allowlist que o SDK liga sozinho aceita só localhost e responde 421 a todo cliente externo. Quem controla acesso aqui é a credencial do OMIE, não o header Host: uma página maliciosa que "rebindou" DNS não tem a app_key de ninguém. Se quiser a checagem ligada de todo modo, declare ali os hostnames pelos quais os clientes chegam (ver .env.example).

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>" }
    }
  }
}

Se preferir não lidar com base64, os headers próprios são equivalentes:

{
  "mcpServers": {
    "omie-finance-mcp": {
      "type": "http",
      "url": "https://seu-servidor/mcp",
      "headers": {
        "X-Omie-App-Key": "app_key_do_cliente",
        "X-Omie-App-Secret": "app_secret_do_cliente"
      }
    }
  }
}

Testes

uv sync --extra dev
uv run pytest

Nenhum teste fala com a API do OMIE: o OmieClient é substituído por um dublê, e os testes de HTTP sobem o servidor de verdade em 127.0.0.1 numa porta livre.

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
│   ├── config.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
├── tests/
│   ├── test_auth.py
│   ├── test_http_multitenant.py
│   └── test_http_session_hijack.py
├── Dockerfile
├── docker-compose.yml
├── .env.example
└── pyproject.toml

Licença

MIT — veja LICENSE.