Brazilian Dev MCP

Servidor MCP (Model Context Protocol) com ferramentas utilitárias para desenvolvedores que trabalham com dados brasileiros — CPF, CNPJ, CEP, telefones, moeda, validações, dados fake e mais.

Instalação

git clone https://github.com/dan94k/brazilian-dev-mcp.git
cd brazilian-dev-mcp
npm install

Uso

Com Claude Desktop

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "brazilian-dev": {
      "command": "npx",
      "args": ["tsx", "caminho/para/brazilian-dev-mcp/src/index.js"]
    }
  }
}

Com opencode

Adicione ao seu opencode.json (no diretório do projeto ou em ~/.config/opencode/opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "brazilian-dev": {
      "type": "local",
      "command": ["npx", "tsx", "caminho/para/brazilian-dev-mcp/src/index.js"],
      "enabled": true
    }
  }
}

Após salvar, reinicie o opencode para que as mudanças tenham efeito.

Com MCP Inspector (desenvolvimento)

npm run dev

Tools

Tool	Descrição	Status
`validar_cpf`	Valida se um CPF é válido e retorna o motivo da invalidez	✅
`gerar_cpf`	Gera um CPF válido aleatório (módulo 11)	✅
`validar_cnpj`	Valida CNPJ (formato numérico e alfanumérico)	✅
`gerar_cnpj`	Gera um CNPJ válido aleatório (módulo 11)	✅
`consultar_cep`	Consulta endereço pelo CEP na API ViaCEP	✅
`validar_cep`	Valida CEP com regex `/^\d{5}-?\d{3}$/`	✅
`consultar_cotacao`	Consulta cotação de moedas (BRL, USD, EUR) via API AwesomeAPI	✅
`validar_email`	Valida e-mail com regex	⬜
`validar_url`	Valida URL usando construtor nativo `URL`	⬜
`validar_ipv4`	Valida IPv4 (4 octetos de 0-255)	⬜
`validar_ipv6`	Valida IPv6 (8 grupos de 4 hex)	⬜
`gerar_lorem`	Gera Lorem Ipsum com X palavras	⬜
`eh_feriado`	Verifica se uma data é feriado nacional	⬜
`eh_dia_util`	Verifica se uma data é dia útil	⬜

Arquitetura

src/
  index.js              → Entrypoint: cria McpServer, conecta StdioServerTransport
  registerTools.js      → Registra todas as tools no servidor
  handlers/             → Um arquivo por tool handler
    validateCPF.js
    generateCPF.js
    validateCNPJ.js
    generateCNPJ.js
    validateCEP.js
    searchCEP.js
    getCurrencyQuote.js

Design: Tools independentes

Cada tool é autocontida. Os handlers não dependem de outros arquivos do projeto — cada um contém toda a lógica necessária para funcionar. Isso significa que alguns códigos podem estar duplicados entre handlers, e isso é intencional. O objetivo é:

Zero acoplamento: cada tool pode ser entendida, testada e modificada isoladamente
Facilidade de contribuição: basta criar um handler novo em src/handlers/ e registrar em registerTools.js

Convenção de idioma

pt-BR (português brasileiro): tudo que o usuário final vê ou interage — nomes de tools, parâmetros, descrições, mensagens de retorno, propriedades do JSON de resposta.
Inglês: código interno — variáveis, funções, imports, lógica, nomes de arquivos

Exemplo: a tool se chama validar_cpf, mas a função interna é validateCPF.

Contribuindo

Contribuições são muito bem-vindas! Sinta-se livre para:

Implementar novas tools da lista de planejadas acima
Reportar bugs via Issues
Sugerir novas funcionalidades que não estão na lista
Melhorar documentação ou testes

Padrões para novas tools

Handler exporta uma função nomeada (em inglês)
Input schema usa z.object() do zod
Handler retorna { content: [{ type: "text", text: JSON.stringify(result) }] }
Nomes de tools, parâmetros e descrições em pt-BR
Código interno em inglês
Cada handler é independente — não importe outros handlers

Stack

Runtime: Node.js (ESM)
Execução: tsx
Schema: zod
MCP SDK: @modelcontextprotocol/sdk
Testes: vitest

Licença

MIT

brazilian dev mcp