consultar_cnpj
Fetch Brazilian company registration details by CNPJ. Returns legal name, status, address, CNAE, partners, and financial data in JSON.
Instructions
Consulta dados cadastrais de uma empresa brasileira pelo CNPJ na Receita Federal (via BrasilAPI). Retorna em JSON: razão social, nome fantasia, situação cadastral (ativa/baixada/etc), data de abertura, endereço completo, CNAE principal e secundários, sócios (QSA), capital social, natureza jurídica, porte (MEI/ME/EPP/Demais), telefones, e-mail, simples nacional/MEI. Use quando o usuário pedir informações sobre uma empresa identificada por CNPJ. NÃO use para: CPF (pessoa física), empresas estrangeiras, ou validação local de formato (rejeite formato inválido sem chamar a tool). Aceita CNPJ com ou sem máscara.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cnpj | Yes | CNPJ da empresa, com ou sem máscara. Aceita '12.345.678/0001-90' ou '12345678000190'. Deve ter 14 dígitos. |
Implementation Reference
- src/tools/cnpj.ts:71-114 (handler)The main function that executes the consultar_cnpj tool logic: validates input, calls BrasilAPI, and returns formatted results or error messages.
export async function consultarCnpjHandler( input: ConsultarCnpjInput, ): Promise<CallToolResult> { const cnpjLimpo = limparCnpj(input.cnpj); if (!validarCnpj(cnpjLimpo)) { return { content: [ { type: "text", text: `CNPJ inválido: '${input.cnpj}'. Deve conter 14 dígitos (com ou sem máscara) e não pode ser uma sequência repetida.`, }, ], isError: true, }; } try { const dados = await brasilApi.get<unknown>(`/cnpj/v1/${cnpjLimpo}`); return { content: [ { type: "text", // JSON estruturado, não texto livre — o modelo extrai campos com // mais confiabilidade quando recebe JSON. text: JSON.stringify(dados, null, 2), }, ], }; } catch (err) { return { content: [ { type: "text", text: traduzirErroBrasilApi(err, { notFound: `CNPJ ${cnpjLimpo} não encontrado na base da Receita Federal. Verifique se está correto.`, contextoErro: "Erro ao consultar CNPJ", }), }, ], isError: true, }; } } - src/tools/cnpj.ts:20-26 (schema)Zod schema for the consultar_cnpj tool input, defining the 'cnpj' field with description.
export const consultarCnpjSchema = z.object({ cnpj: z .string() .describe( "CNPJ da empresa, com ou sem máscara. Aceita '12.345.678/0001-90' ou '12345678000190'. Deve ter 14 dígitos.", ), }); - src/index.ts:81-88 (registration)Registration of consultar_cnpj tool into the MCP server via registerTool with name, description, schema, and wrapped handler.
server.registerTool( consultarCnpjTool.name, { description: consultarCnpjTool.description, inputSchema: consultarCnpjSchema.shape, }, wrapHandler(consultarCnpjTool.name, consultarCnpjHandler), ); - src/tools/cnpj.ts:50-52 (helper)Helper function to strip non-digit characters from CNPJ input.
function limparCnpj(s: string): string { return s.replace(/\D/g, ""); } - src/tools/cnpj.ts:65-69 (helper)Helper function to validate CNPJ format: exactly 14 digits and not all repeated digits.
function validarCnpj(s: string): boolean { if (!/^\d{14}$/.test(s)) return false; if (/^(\d)\1{13}$/.test(s)) return false; return true; }