brazil-mcp

# 🇧🇷 Brazil MCP Bundle — Brazilian Business Tools for AI Agents Give your AI agent superpowers to interact with the Brazilian economy. Directly query national registries, issue invoices, generate Pix payments, and communicate via WhatsApp using the **Model Context Protocol (MCP)**. Works seamlessly with **Claude Code**, **Cursor**, **VS Code Copilot**, **Windsurf**, **Smithery**, and any MCP-compatible AI client. --- ## ⚡ What Can Your AI Agent Do? With **Brazil MCP Bundle**, your AI assistant can execute real-world business workflows in Brazil directly through natural language prompts: - 🏢 **CNPJ Intelligence:** Consult complete corporate records from *Receita Federal* — verify company status, capital, CNAE activities, registered address, and full partner lists (QSA). - 📍 **CEP Geocoding:** Instant postal code lookups, address auto-completion, and IBGE/DDD location data via *ViaCEP* and *BrasilAPI*. - 💸 **Pix Payments:** Generate dynamic Pix QR Codes, copy-and-paste payment strings, monitor transaction statuses, and manage charges across major Brazilian fintech gateways. - 🧾 **NFSe Electronic Invoicing:** Emit municipal service invoices (Nota Fiscal de Serviço Eletrônica), track tax processing status, and cancel invoices automatically. - 💬 **WhatsApp Notifications:** Send instant transactional text alerts and official interactive templates to customers via the *Meta Cloud API*. --- ## 🛠️ Tool Suite Overview We operate on a transparent **Freemium** model tailored for developers and enterprises: ### 🟢 Free Tier (Available via NPM CLI) Ideal for validation, personal projects, and standard queries *(up to 50 calls/day)*: - `cnpj_lookup` — Complete company registration data by CNPJ - `cnpj_validate` — Local check-digit mathematical validation *(unlimited / local)* - `cnpj_partners` — Corporate structure and partner list (QSA) - `cnpj_activities` — Primary and secondary CNAE economic codes - `cnpj_address` — Official tax address registered at Receita Federal - `cep_lookup` — Street, neighborhood, city, state, and IBGE code by CEP - `cep_validate` — Local CEP format verification *(unlimited / local)* ### 🚀 Bundle Pro (Unlimited Access & Core Business Tools) Designed for production workflows, autonomous agents, and SaaS platforms *(Unlimited queries + 16 enterprise tools)*: - **Unlimited CNPJ & CEP queries** - `pix_create_charge` — Create Pix charges with QR codes & copy-paste strings - `pix_check_status` — Real-time payment verification - `pix_list_charges` — Query historical transactions by period - `pix_cancel_charge` — Cancel pending Pix charges - `nfse_emit` — Emit electronic service invoices (NFSe) - `nfse_status` — Check municipal invoice authorization - `nfse_cancel` — Cancel issued invoices - `whatsapp_send_text` — Send free-form WhatsApp messages - `whatsapp_send_template` — Dispatch pre-approved interactive templates > **Supported Pix Gateways:** Asaas · Mercado Pago · EFI Bank (Gerencianet) · PagSeguro · Stripe · Pagar.me · AbacatePay --- ## 🚀 Quick Start ### Option 1: Connect via Smithery Gateway (Recommended) Connect your AI client directly via Smithery using your Pro API Key: - **SSE Server URL:** `https://brazil.mcpize.run/sse` - **Authentication Header:** `Authorization: Bearer <YOUR_API_KEY>` ### Option 2: Local Free Tier via CLI Add the free tools directly to Claude Code or Cursor: ```bash # CNPJ Free Tools claude mcp add cnpj -- npx @brazil-mcp/cnpj # CEP Free Tools claude mcp add cep -- npx @brazil-mcp/cep