# mcp-conta-azul

An MCP server that connects an AI agent to Conta Azul: customers, products, services, sales, receivables and a financial summary.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 274
- Author: codespar
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/codespar/mcp-dev-latam/tree/HEAD/packages/fiscal/conta-azul
- Updated: 2026-09-27
- HTML: https://affpapa.org/en/nevibecode/mcp/mcp-conta-azul

## What it does

Twenty tools wrap the Conta Azul API. Your agent can page through customers, products and services, edit or remove them, create and cancel sales, and pull the financial summary along with categories, bank accounts and receivables. Writes land in the live account, so a `cancel_sale` typed into a chat really cancels it.

Access goes through an OAuth2 bearer token. Register at the Conta Azul developer portal, create an OAuth application, then export the resulting token as `CONTA_AZUL_ACCESS_TOKEN`. Nothing starts without it. A sandbox is available through the same OAuth flow, and testing there first is the sensible move.

Setup is a single command on Claude or Codex; Cursor and GitHub Copilot take a JSON block in their config file. Conta Azul is a Brazilian product, its data and UI are in Portuguese. Tokens expire, so an empty answer usually means the credential needs refreshing.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `CONTA_AZUL_ACCESS_TOKEN` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add mcp-conta-azul -e CONTA_AZUL_ACCESS_TOKEN=<CONTA_AZUL_ACCESS_TOKEN> -- npx -y @codespar/mcp-conta-azul
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add conta-azul --env CONTA_AZUL_ACCESS_TOKEN=<CONTA_AZUL_ACCESS_TOKEN> -- npx -y @codespar/mcp-conta-azul
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "conta-azul": {
            "command": "npx",
            "args": [
                "-y",
                "@codespar/mcp-conta-azul"
            ],
            "env": {
                "CONTA_AZUL_ACCESS_TOKEN": "<CONTA_AZUL_ACCESS_TOKEN>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "conta-azul": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@codespar/mcp-conta-azul"
            ],
            "env": {
                "CONTA_AZUL_ACCESS_TOKEN": "<CONTA_AZUL_ACCESS_TOKEN>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e CONTA_AZUL_ACCESS_TOKEN=<CONTA_AZUL_ACCESS_TOKEN> conta-azul npx -y @codespar/mcp-conta-azul
```
Replace <…> with your own values

## When to use it
- pull the customer list out of Conta Azul into a chat
- record a sale from details discussed with the agent
- look up a receivable and check where it stands
- fix a product or service record without opening the web UI
- read the financial summary for a period

## Example prompts
- List every Conta Azul customer that has no email address
- Create a sale for the customer from that last email and add a consulting service
- Show the financial summary and the open receivables

## Similar
- [World Monitor](https://affpapa.org/en/nevibecode/mcp/world-monitor.md) — MCP server · ★ 89408
- [CCXT](https://affpapa.org/en/nevibecode/mcp/ccxt.md) — MCP server · ★ 44583
- [Finance Toolkit](https://affpapa.org/en/nevibecode/mcp/finance-toolkit.md) — MCP server · ★ 5458
- [EdgarTools](https://affpapa.org/en/nevibecode/mcp/edgartools.md) — MCP server · ★ 2814
- [LetsFG — Flights & Hotels](https://affpapa.org/en/nevibecode/mcp/letsfg-flights-hotels.md) — MCP server · ★ 2188
- [AutoTS](https://affpapa.org/en/nevibecode/mcp/autots.md) — MCP server · ★ 1434

From the same set: [codespar/mcp-dev-latam](https://affpapa.org/en/nevibecode/by/codespar/mcp-dev-latam.md) — 40 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md