# Brasil API MCP A Model Context Protocol (MCP) server that provides tools to query various Brazilian data services via the [Brasil API](https://brasilapi.com.br/). ## Overview Brasil API MCP is a bridge that connects AI assistants to Brazilian public data services through the standardized Model Context Protocol. It provides access to various information such as: - Postal Codes (CEP) - Company Registration (CNPJ) - Bank information - Area codes (DDD) - IBGE (Brazilian Institute of Geography and Statistics) data - Currency exchange rates - Domain registration status (.br domains) ## Installation \`\`\`bash # Clone the repository git clone https://github.com/guilhermelirio/brasil-api-mcp cd brasil-api-mcp # Install dependencies npm install # Build the project npm run build \`\`\` ## Usage To run the server: \`\`\`bash npm start \`\`\` This will start the MCP server that communicates via standard input/output (stdio). ## Available Tools ### CEP (Postal Codes) - \`cep-search\` - Query address information from a Brazilian postal code (CEP) ### CNPJ (Company Registration) - \`cnpj-search\` - Query information about a Brazilian company by its CNPJ (National Registry of Legal Entities) ### Banks - \`bank-search\` - Find information about a Brazilian bank by its code - \`bank-list\` - List all Brazilian banks ### DDD (Area Codes) - \`ddd-search\` - Find information about a Brazilian area code (DDD) ### IBGE (Geography and Statistics) - \`ibge-states-list\` - List all Brazilian states with their information - \`ibge-state-search\` - Find information about a Brazilian state by its code or abbreviation - \`ibge-municipalities-list\` - List all municipalities of a Brazilian state by its abbreviation ### Cambio (Currency Exchange) - \`cambio-currencies-list\` - List all available currencies for exchange rates - \`cambio-rate\` - Get exchange rates for a specific currency on a specific date ### Registro BR (Domain Registration) - \`registrobr-domain-check\` - Check the status and availability of a .br domain name ## Integration Examples ### Querying a Brazilian Address by Postal Code \`\`\`typescript // Sample request to the CEP tool const response = await callMcpTool("cep-search", \{ cep: "01001000" \}); // Response provides address details: // \{ // cep: "01001000", // state: "SP", // city: "São Paulo", // neighborhood: "Sé", // street: "Praça da Sé", // service: "viacep" // \} \`\`\` ### Getting Currency Exchange Rates \`\`\`typescript // Sample request to get USD exchange rate const response = await callMcpTool("cambio-rate", \{ currency: "USD", date: "2023-08-10" \}); // Response provides detailed exchange information \`\`\` ## Credits This project uses the [Brasil API](https://brasilapi.com.br/) service, which aggregates various APIs related to Brazilian public data. Special thanks to the Brasil API team for providing this valuable service to the community. ## License MIT © [Guilherme Lirio Tomasi de Oliveira](https://github.com/guilhermelirio)