mcp-conta-azul — Conta Azul MCP server: invoices, customers, sales
An MCP server that connects an AI agent to Conta Azul: customers, products, services, sales, receivables and a financial summary.
claude mcp add mcp-conta-azul -e CONTA_AZUL_ACCESS_TOKEN=<CONTA_AZUL_ACCESS_TOKEN> -- npx -y @codespar/mcp-conta-azulWhat mcp-conta-azul 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.
What it helps with
- 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 for the agent
- 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
How to install mcp-conta-azul
Platform CLI
claude mcp add mcp-conta-azul -e CONTA_AZUL_ACCESS_TOKEN=<CONTA_AZUL_ACCESS_TOKEN> -- npx -y @codespar/mcp-conta-azulReplace <…> with your own values
Platform CLI
codex mcp add conta-azul --env CONTA_AZUL_ACCESS_TOKEN=<CONTA_AZUL_ACCESS_TOKEN> -- npx -y @codespar/mcp-conta-azulReplace <…> with your own values
Config file
{
"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
Config file
{
"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
Platform CLI
gemini mcp add -e CONTA_AZUL_ACCESS_TOKEN=<CONTA_AZUL_ACCESS_TOKEN> conta-azul npx -y @codespar/mcp-conta-azulReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about mcp-conta-azul
How do I install mcp-conta-azul in Claude Code?
Run claude mcp add mcp-conta-azul -e CONTA_AZUL_ACCESS_TOKEN=<CONTA_AZUL_ACCESS_TOKEN> -- npx -y @codespar/mcp-conta-azul. Alternatively use claude mcp add --env CONTA_AZUL_ACCESS_TOKEN=<CONTA_AZUL_ACCESS_TOKEN> --transport stdio conta-azul -- npx -y @codespar/mcp-conta-azul.
What does mcp-conta-azul do?
It hands the agent 20 Conta Azul tools: customers, products, services, sales, categories, bank accounts, receivables and a financial summary.
What do I need before it will connect?
An OAuth2 access token from the Conta Azul developer portal, stored in CONTA_AZUL_ACCESS_TOKEN. You get one after registering an OAuth app; the sandbox is there for trial runs.
