br-docs-mcp
Servidor MCP para validar/gerar documentos brasileiros (CPF e CNPJ) e validar/parsear boletos, com resource de regras e prompt de auditoria.
Validar CPF formatado ou cru, retornando
{ valid }e motivo quando inválido.Gerar CPF válido aleatório, opcionalmente formatado.
Validar CNPJ formatado ou cru, retornando
{ valid }e motivo quando inválido.Gerar CNPJ válido aleatório, opcionalmente formatado.
Validar linha digitável de boleto com 47 dígitos, conferindo mod10 dos campos e DV geral mod11.
Extrair banco, valor e vencimento de um boleto.
Ler o resource
docs://validation-rulescom a documentação dos algoritmos.Usar o prompt
audit_customer_recordpara auditar cadastros usando as tools.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@br-docs-mcp Validate CPF 529.982.247-25"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
br-docs-mcp
Servidor MCP (Model Context Protocol) para validação e geração de documentos brasileiros: CPF, CNPJ e boleto bancário.
O que é
Uma implementação de servidor MCP que expõe 6 ferramentas para validar e gerar documentos brasileiros. Implementa os algoritmos de validação (módulo 11 para CPF e CNPJ, módulo 10 e 11 para boleto) e permite que clientes MCP (Claude, Cursor, etc.) utilizem essas funcionalidades via chamadas de ferramentas.
Related MCP server: mcp-server-brasil
Funcionalidades e Tecnologias
Funcionalidade | Descrição | Tecnologia |
Validação de CPF | Valida CPF com algoritmo mod11, aceita formatado e bruto | TypeScript |
Geração de CPF | Gera CPF válido e aleatório | Pure logic |
Validação de CNPJ | Valida CNPJ com pesos mod11 específicos | TypeScript |
Geração de CNPJ | Gera CNPJ válido e aleatório | Pure logic |
Validação de Boleto | Valida linha digitável (47 dígitos, layout FEBRABAN): mod10 nos 3 campos + DV geral mod11 na posição 33 | TypeScript |
Parse de Boleto | Extrai banco, valor e vencimento via fator de vencimento (com rollover de 22/02/2025) | Pure logic |
MCP Tools | Expõe 6 ferramentas via Model Context Protocol | @modelcontextprotocol/sdk |
MCP Resource |
| Markdown |
MCP Prompt |
| Template |
Testes | 40 testes, incluindo E2E MCP real (Client ↔ Server via InMemoryTransport) | Vitest |
Clean Architecture | Lógica pura separada da camada MCP | src/domain |
Arquitetura
graph TB
subgraph Client["Cliente MCP (Claude, Cursor)"]
A["Chamada de Tool<br/>ou Leitura de Resource"]
end
subgraph Transport["Transporte"]
B["Stdio Transport<br/>JSON-RPC 2.0"]
end
subgraph Server["br-docs-mcp Server"]
C1["Tool: validate_cpf"]
C2["Tool: generate_cpf"]
C3["Tool: validate_cnpj"]
C4["Tool: generate_cnpj"]
C5["Tool: validate_boleto"]
C6["Tool: parse_boleto"]
C7["Resource: docs://validation-rules"]
C8["Prompt: audit_customer_record"]
end
subgraph Domain["Lógica Pura"]
D1["src/domain/cpf.ts"]
D2["src/domain/cnpj.ts"]
D3["src/domain/boleto.ts"]
end
A --> B --> C1
C1 --> D1
C2 --> D1
C3 --> D2
C4 --> D2
C5 --> D3
C6 --> D3
style Domain fill:#e1f5ff
style Server fill:#f3e5f5
style Transport fill:#fff3e0Como rodar
Pré-requisitos
Node.js >= 22.12
Instalação
npm installDesenvolvimento
npm run devBuild
npm run buildSaída em dist/index.js com shebang, pronto para uso via npx br-docs-mcp.
Como testar
Rodar testes
npm testModo watch
npm run test:watchType check
npm run type-checkTodos os 40 testes rodam 100% offline e cobrem:
Validação de CPF/CNPJ formatado e bruto
Rejeição de dígito verificador errado, comprimento inválido, dígitos repetidos
Roundtrip gerar → validar (20 iterações para CPF e CNPJ)
Boleto: linha válida construída nos testes (com mod10/mod11 independentes), campos corrompidos, DV geral errado
Parse de boleto: banco, valor e vencimento — incluindo o rollover do fator (1000 = 22/02/2025) e fator 0000 (sem vencimento)
E2E MCP real:
ClienteMcpServerconectados porInMemoryTransport.createLinkedPair(), listando as 6 tools, chamandovalidate_cpf, lendo o resource e obtendo o prompt
Uso com clientes MCP
Configuração no Claude Desktop / Cursor
Adicione a entrada no mcp.json:
{
"mcpServers": {
"br-docs-mcp": {
"command": "npx",
"args": ["br-docs-mcp"]
}
}
}Exemplo de chamada
{
"name": "validate_cpf",
"arguments": {
"cpf": "529.982.247-25"
}
}Resposta:
{
"valid": true
}Ferramentas disponíveis
validate_cpf- Valida CPF →{ "valid": true }ou{ "valid": false, "reason": "check digit mismatch" }generate_cpf- Gera CPF válido →{ "cpf": "..." }validate_cnpj- Valida CNPJgenerate_cnpj- Gera CNPJ válidovalidate_boleto- Valida linha digitável de boletoparse_boleto- Extrai dados do boleto →{ "bankCode": "001", "amount": 1500, "dueDate": "2025-02-22" }
Resource disponível
docs://validation-rules- Documentação dos algoritmos
Prompt disponível
audit_customer_record- Audita registros de clientes usando as tools
Estrutura do projeto
.
├── src/
│ ├── domain/
│ │ ├── cpf.ts # Lógica pura de CPF
│ │ ├── cnpj.ts # Lógica pura de CNPJ
│ │ └── boleto.ts # Lógica pura de boleto (layout FEBRABAN)
│ ├── server.ts # Servidor MCP (tools, resource, prompt)
│ ├── validation-rules.ts # Markdown servido pelo resource
│ └── index.ts # Entrypoint stdio (#!/usr/bin/env node)
├── tests/
│ ├── domain/
│ │ ├── cpf.test.ts
│ │ ├── cnpj.test.ts
│ │ └── boleto.test.ts
│ └── e2e/
│ └── server.test.ts
├── package.json # bin: br-docs-mcp → dist/index.js
├── tsconfig.json
├── vitest.config.ts
├── README.md # Este arquivo
├── LICENSE # MIT
└── .gitignorePublicação no npm
Build e teste
npm run type-check
npm test
npm run buildPublicar
npm publishO script prepublishOnly garante que testes e build passam antes de publicar.
Origem
Inspirado em conceitos do curso de pós-graduação em Engenharia de Software com IA Aplicada — implementação própria do zero, usando TypeScript e clean architecture para demonstrar:
Design domain-driven
Separação de responsabilidades (domain vs. transport)
Algoritmos de validação (mod11, mod10)
Model Context Protocol (MCP)
Test-driven development com Vitest
Empacotamento npm com tipos
Licença
MIT - Copyright (c) 2026 Vicente Moura
Available Tools
6 toolsgenerate_cnpjA
Gera um CNPJ válido aleatório. Use formatted=true para "XX.XXX.XXX/XXXX-XX".
Inputs: formatted.
generate_cpfA
Gera um CPF válido aleatório. Use formatted=true para "XXX.XXX.XXX-XX".
Inputs: formatted.
parse_boletoA
Extrai código do banco, valor (R$) e data de vencimento da linha digitável de um boleto. Falha com mensagem clara se a linha for inválida.
Inputs: linha_digitavel (required).
validate_boletoA
Valida a linha digitável de um boleto bancário (47 dígitos, aceita pontuação). Confere o mod 10 dos 3 campos e o DV geral mod 11. Retorna { valid } e { reason } quando inválido.
Inputs: linha_digitavel (required).
validate_cnpjA
Valida um CNPJ brasileiro (aceita formatado "11.222.333/0001-81" ou cru). Retorna { valid } e, quando inválido, { reason }.
Inputs: cnpj (required).
validate_cpfA
Valida um CPF brasileiro (aceita formatado "529.982.247-25" ou cru "52998224725"). Retorna { valid } e, quando inválido, { reason }.
Inputs: cpf (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool targets a distinct document type and action. CPF, CNPJ, and boleto are clearly different domains, and validate vs. generate vs. parse have well-defined boundaries. Even the two boleto tools are unambiguous: one checks validity, the other extracts data.
All tool names follow a strict verb_noun pattern in lowercase snake_case: validate_cpf, generate_cpf, validate_cnpj, generate_cnpj, validate_boleto, parse_boleto. The verb (validate/generate/parse) and noun (cpf/cnpj/boleto) are consistent and predictable.
Six tools is well within the ideal 3-15 range and each tool provides a distinct function for Brazilian documents. The count feels neither sparse nor bloated, covering validation, generation, and parsing for three common document types.
The surface covers the core lifecycle for each document type: CPF and CNPJ have both generation and validation (with formatted output options), and boleto has validation and parsing. There are no obvious dead ends or missing operations for the stated purpose.
Related MCP Connectors
# MCP DadosBR Servidor MCP focado em dados públicos do Brasil. Oferece duas ferramentas simples e…
Official MCP server for Certifier to issue, manage, and track certificates and badges.
MCP registry & directory: search, find & install 31k+ MCP servers & tools. Catalog and marketplace.
Official Timbrix MCP server: stamp, cancel, and query Mexican CFDI 4.0 invoices from AI agents.
Related MCP Servers
AlicenseAqualityCmaintenanceA privacy-first MCP server providing 14 offline Brazilian utilities including document validation, boleto parsing, PIX BR Code generation/parsing, and calendar tools.221MIT- AlicenseAqualityDmaintenanceProvides tools to query Brazilian CNPJ (company registration), CEP (postal codes), and currency exchange rates (USD and EUR) through an MCP server.3MIT
- AlicenseAqualityDmaintenanceMCP server with tools for Brazilian data like CPF, CNPJ, CEP validation and generation, and currency quotes.750 npmMIT
- FlicenseNot gradedqualityBmaintenanceMCP server for generating and validating Brazilian documents (CPF, CNPJ, CNH, RG, PIS/PASEP, RENAVAM), encoding/decoding data (Base64, MD5, SHA1, URL), and performing text utilities like removing accents, reversing, and analyzing text.-