cnpj-search
Retrieve detailed information about Brazilian companies using their CNPJ (National Registry of Legal Entities) through the Brasil API MCP server.
Instructions
Query information about a Brazilian company by its CNPJ (National Registry of Legal Entities)
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cnpj | Yes | CNPJ to be queried (only numbers, 14 digits) |
Input Schema (JSON Schema)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"cnpj": {
"description": "CNPJ to be queried (only numbers, 14 digits)",
"pattern": "^\\d{14}$",
"type": "string"
}
},
"required": [
"cnpj"
],
"type": "object"
}
Implementation Reference
- src/tools/cnpj/index.ts:19-54 (handler)Handler function that queries the Brasil API for CNPJ data, handles errors, and formats the company information into a text response.async ({ cnpj }) => { console.error(`Consulting CNPJ: ${cnpj}`); const result = await getBrasilApiData(`/cnpj/v1/${cnpj}`); if (!result.success) { return formatErrorResponse(`Error querying CNPJ: ${result.message}`); } // Format the response data const company = result.data; return { content: [{ type: "text" as const, text: ` Informações da Empresa: CNPJ: ${company.cnpj} Razão Social: ${company.razao_social} Nome Fantasia: ${company.nome_fantasia || "N/A"} Situação Cadastral: ${company.descricao_situacao_cadastral || "N/A"} Data de Abertura: ${company.data_inicio_atividade || "N/A"} CNAE Principal: ${company.cnae_fiscal} - ${company.cnae_fiscal_descricao || "N/A"} Natureza Jurídica: ${company.codigo_natureza_juridica} - ${company.natureza_juridica || "N/A"} Endereço: ${company.logradouro || ""} ${company.numero || ""} ${company.complemento || ""} ${company.bairro || ""}, ${company.municipio || ""} - ${company.uf || ""} CEP: ${company.cep || "N/A"} Contato: Telefone: ${company.ddd_telefone_1 || "N/A"} Email: ${company.email || "N/A"} ` }] }; }
- src/tools/cnpj/index.ts:14-18 (schema)Zod schema defining the input parameter 'cnpj' with validation for 14-digit format.{ cnpj: z.string() .regex(/^\d{14}$/, "CNPJ must contain exactly 14 numbers without any special characters") .describe("CNPJ to be queried (only numbers, 14 digits)") },
- src/tools/cnpj/index.ts:9-56 (registration)Function that registers the 'cnpj-search' tool on the MCP server, including schema and handler.export function registerCnpjTools(server: McpServer) { // Tool to query information about a Brazilian company by its CNPJ server.tool( "cnpj-search", "Query information about a Brazilian company by its CNPJ (National Registry of Legal Entities)", { cnpj: z.string() .regex(/^\d{14}$/, "CNPJ must contain exactly 14 numbers without any special characters") .describe("CNPJ to be queried (only numbers, 14 digits)") }, async ({ cnpj }) => { console.error(`Consulting CNPJ: ${cnpj}`); const result = await getBrasilApiData(`/cnpj/v1/${cnpj}`); if (!result.success) { return formatErrorResponse(`Error querying CNPJ: ${result.message}`); } // Format the response data const company = result.data; return { content: [{ type: "text" as const, text: ` Informações da Empresa: CNPJ: ${company.cnpj} Razão Social: ${company.razao_social} Nome Fantasia: ${company.nome_fantasia || "N/A"} Situação Cadastral: ${company.descricao_situacao_cadastral || "N/A"} Data de Abertura: ${company.data_inicio_atividade || "N/A"} CNAE Principal: ${company.cnae_fiscal} - ${company.cnae_fiscal_descricao || "N/A"} Natureza Jurídica: ${company.codigo_natureza_juridica} - ${company.natureza_juridica || "N/A"} Endereço: ${company.logradouro || ""} ${company.numero || ""} ${company.complemento || ""} ${company.bairro || ""}, ${company.municipio || ""} - ${company.uf || ""} CEP: ${company.cep || "N/A"} Contato: Telefone: ${company.ddd_telefone_1 || "N/A"} Email: ${company.email || "N/A"} ` }] }; } ); }
- src/utils/api.ts:11-40 (helper)Utility function to make API requests to BrasilAPI and handle responses/errors.export async function getBrasilApiData(endpoint: string, params: Record<string, any> = {}) { try { const url = `${BASE_URL}${endpoint}`; console.error(`Making request to: ${url}`); const response = await axios.get(url, { params }); return { data: response.data, success: true }; } catch (error: any) { console.error(`Error in API request: ${error.message}`); // Handle API errors in a structured format if (error.response) { return { success: false, statusCode: error.response.status, message: error.response.data?.message || error.message, error: error.response.data }; } return { success: false, message: error.message, error }; } }
- src/utils/api.ts:47-55 (helper)Utility function to format error messages into MCP-compatible responses.export function formatErrorResponse(message: string) { return { content: [{ type: "text" as const, text: message }], isError: true }; }