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