# MCP Conta Azul

MCP (Model Context Protocol) server for [Conta Azul](https://contaazul.com) 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

```bash
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

```bash
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`:

```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](https://developers.contaazul.com/docs/financial-apis-openapi).

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

## License

MIT