MCP Conta Azul

MCP (Model Context Protocol) server for Conta Azul Financial APIs. Enables AI assistants like Claude to interact with your Conta Azul financial data through natural language.

Features

API Tools (14)

Tool	Type	Description
list_cost_centers	GET	List cost centers with filters
create_cost_center	POST	Create a new cost center
list_categories	GET	List financial categories (revenue/expense)
list_dre_categories	GET	List DRE categories
list_financial_accounts	GET	List financial accounts (bank, card, savings, etc)
get_account_balance	GET	Get current balance of a financial account
list_transfers	GET	List transfers between accounts by period
create_receivable	POST	Create accounts receivable event with installments
search_receivables	GET	Search receivables by due date, status, amount, client
create_payable	POST	Create accounts payable event with installments
search_payables	GET	Search payables by due date, status, amount
get_installments_by_event	GET	List installments for a financial event
get_installment	GET	Get installment details
update_installment	PATCH	Update installment (due date, amount, payment method)

Smart Tools (7)

Tool	Description
get_financial_dashboard	Overview: all account balances + totals + overdue
get_cash_flow	Cash flow by period, revenue vs expenses by month
get_overdue_summary	Full overdue summary (payables + receivables)
list_upcoming_payments	Upcoming due dates in N days
list_overdue_receivables	Overdue receivables for collection, with days overdue
search_by_contact	All transactions for a client/supplier by name
get_monthly_report	Monthly report: revenue vs expenses by category

Setup

Prerequisites

• Node.js 18+
• Conta Azul API credentials

Installation

git clone https://github.com/ebrahimpleite/mcp-contaazul.git
cd mcp-contaazul
npm install

Configuration

The server requires two environment variables for authentication:

Variable	Description
CONTAAZUL_API_KEY	Your API key for token endpoint
CONTAAZUL_API_TOKEN	Your API token for token endpoint

Adding to Claude Code

claude mcp add --scope user --transport stdio contaazul \
  --env CONTAAZUL_API_KEY="your_key" \
  --env CONTAAZUL_API_TOKEN="your_token" \
  -- node /path/to/mcp-contaazul/index.js

Adding to Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "contaazul": {
      "command": "node",
      "args": ["/path/to/mcp-contaazul/index.js"],
      "env": {
        "CONTAAZUL_API_KEY": "your_key",
        "CONTAAZUL_API_TOKEN": "your_token"
      }
    }
  }
}

Authentication

The server authenticates via a token endpoint that returns a Bearer JWT token. Tokens are cached for 50 minutes and automatically refreshed when expired.

API Reference

Based on the Conta Azul Financial APIs OpenAPI spec.

Base URL: https://api-v2.contaazul.com

License

MIT