# CNPJ Validator MCP

> CNPJ Validator checks Brazilian business identification numbers (CNPJs) against mathematical algorithms and structural rules. It validates basic format, deconstructs complex IDs into root, branch, and check digits, and handles high-volume batch processing for data cleaning.

## Overview
- **Category:** finance
- **Price:** Free
- **Tags:** cnpj, brazil, validation, business, checksum

## Description

You need to confirm that a CNPJ number is actually valid before you process it. This MCP provides specialized tools to verify Brazilian corporate identifiers using checksum algorithms and structural analysis. You can use your agent to perform precise validation without needing access to external federal databases. For instance, if you're building a data cleaning pipeline or an onboarding form, this tool confirms mathematically whether the number is real, breaks down its components (like finding the root identifier or inferring the state), and even processes large lists of identifiers at once. All these powerful tools are managed through the Vinkius catalog, making it easy for your AI client to connect and start using them immediately.

## Tools

### analyze_cnpj_structure
Deconstructs a CNPJ into its root, branch, check digits, and can infer the state of registration.

### batch_validate_cnpjs
Performs high-volume validation on an entire list of identifiers simultaneously for efficiency.

### validate_cnpj_format
Checks a single CNPJ string immediately using standard checksum algorithms to confirm basic mathematical validity.

## Prompt Examples

**Prompt:** 
```
Is the CNPJ 12.345.678/0001-95 valid?
```

**Response:** 
```
Yes, the CNPJ 12.345.678/0001-95 is mathematically valid.
```

**Prompt:** 
```
Analyze the structure of CNPJ 00.000.000/0001-91.
```

**Response:** 
```
The CNPJ 00.000.000/0001-91 has a root identifier of 00000000, a branch identifier of 0001, and check digits 91. The inferred state is based on regional mapping rules.
```

**Prompt:** 
```
Check if this list of CNPJs are valid: ['12345678000195', '00000000000191']
```

**Response:** 
```
Total processed: 2. Valid count: 2. Invalid count: 0.
```

## Capabilities

### Check Mathematical Validity
Confirms if a CNPJ string passes standard checksum checks.

### Deconstruct ID Components
Breaks down a full CNPJ into its specific parts: the root, branch, and check digits.

### Process Large Batches
Validates an entire list of identifiers in one high-volume operation.

### Infer Regional Data
Uses internal mapping rules to suggest the Brazilian state associated with the ID structure.

## Use Cases

### Cleaning up an imported customer database
A data analyst has downloaded a spreadsheet of 5,000 client IDs. Instead of manually checking them one by one, they run the list through `batch_validate_cnpjs`. The agent returns a clean manifest showing exactly which records are mathematically valid and which need manual correction.

### Validating an onboarding form submission
A user submits a new business profile. Before accepting the data, your agent calls `validate_cnpj_format`. If it returns 'invalid,' the system immediately flags the field and tells the user to correct the number before proceeding.

### Deconstructing an existing ID for reporting
You need to report on which regional branch a client belongs to. You feed the CNPJ into `analyze_cnpj_structure`. The tool breaks it down, giving you the specific root and branch identifiers needed for your executive summary.

### Verifying data before migration
A developer is migrating old client records. They run a sample set through all three tools: first using `validate_cnpj_format` to filter errors, then running the clean list through `analyze_cnpj_structure` to ensure all components are available for the new system schema.

## Benefits

- Confirms data integrity instantly. Instead of guessing if a number is valid, running it through the `validate_cnpj_format` tool gives you immediate confirmation that the CNPJ passes checksum algorithms.
- Saves time on massive datasets. When you have thousands of IDs, use `batch_validate_cnpjs`. It processes huge lists in one go, making data cleanup faster than manual checks.
- Provides deep context beyond just validity. The `analyze_cnpj_structure` tool doesn't just say if it's valid; it breaks the ID into its root and branch components—critical for reporting.
- Reduces compliance risk. By confirming the structure, you build confidence in your data pipeline that the identifiers are correctly formatted before they hit a financial system.
- Offers regional insight. The tool can use internal mapping to suggest the Brazilian state based on how the CNPJ is structured, adding valuable context.

## How It Works

The bottom line is you get clean, mathematically verifiable Brazilian corporate IDs that your workflow can trust.

1. You feed your AI client a CNPJ number or a list of numbers.
2. The MCP first uses checksum algorithms to confirm the basic mathematical integrity and format of the identifier.
3. It then returns a detailed report showing structural components, validation status (valid/invalid), and batch results.

## Frequently Asked Questions

**Does this tool require an internet connection to the Brazilian Federal Revenue?**
No. The `validate_cnpj_format` and other tools use a local checksum algorithm (weighted summation) to verify the mathematical validity of the CNPJ without making external API calls to federal databases.

**Can I validate multiple CNPJs at once?**
Yes, you can use the `batch_validate_cnpjs` tool to process an array of CNPJ strings in a single operation and receive summary statistics.

**What information is returned when analyzing a CNPJ?**
By using `analyze_cnpj_structure`, you will receive the root identifier, branch identifier, check digits, and the inferred Brazilian state (UF) based on regional mapping rules.

**Does the CNPJ Validator use live data from Brazilian government databases?**
No. This MCP validates numbers using internal checksum algorithms and structural rules only. It doesn't require real-time connections to external federal databases, ensuring reliability even if those systems are temporarily unavailable.

**If I use `validate_cnpj_format`, what happens when the input is clearly malformed?**
The tool returns a specific error message detailing the failure. It won't just fail silently; it reports exactly why the number failed, such as an incorrect checksum or wrong character length.

**Does `batch_validate_cnpjs` have usage limits or rate caps?**
Usage is managed through your Vinkius subscription tier. While designed for high throughput, consult the platform documentation if you anticipate enterprise-level volume above standard rates.

**How does the CNPJ Validator handle data security and privacy?**
Data processing stays within the secure MCP framework. The tool never transmits sensitive business identifiers to external third parties, keeping your inputs private throughout validation.

**What is needed to connect my AI agent to this CNPJ Validator MCP?**
You just need an active subscription on Vinkius and compatibility with any MCP-compatible client (like Claude or Cursor). No complex API keys or local server setup is required.