README.md
Enables AI assistants to interact with Conta Azul Financial APIs
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
Tools (7)
get_financial_dashboardProvides an overview of all account balances, totals, and overdue items.get_cash_flowRetrieves cash flow by period, showing revenue vs expenses by month.get_overdue_summaryProvides a full summary of all overdue payables and receivables.list_upcoming_paymentsLists upcoming due dates within a specified number of days.list_overdue_receivablesLists overdue receivables for collection, including days overdue.search_by_contactFinds all transactions for a specific client or supplier by name.get_monthly_reportGenerates a monthly report comparing revenue vs expenses by category.Environment Variables
CONTAAZUL_API_KEYrequiredYour API key for the token endpointCONTAAZUL_API_TOKENrequiredYour API token for the token endpointConfiguration
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"}}}}Try it
→What is my current financial dashboard overview?
→Show me the cash flow report for the last three months.
→List all overdue receivables that I need to collect today.
→How much do I owe in upcoming payments for the next 7 days?
→Generate a monthly report comparing my revenue and expenses by category.