mcp-server-brasil

Brazilian data APIs as MCP tools. Look up CNPJ, CEP, and live exchange rates (USD/BRL, EUR/BRL) from inside any MCP-compatible client -- Claude Desktop, Cursor, Windsurf, and more.

No API keys required. All sources are free and public (ReceitaWS, ViaCEP, AwesomeAPI).

Features

• In-memory cache on every tool -- avoids duplicate requests and respects ReceitaWS rate limits

• Input normalization -- CNPJ/CEP work with or without punctuation

• Built-in validation -- rejects malformed CNPJ/CEP before hitting the network

• Rate-limit guard -- auto-throttles requests to ReceitaWS (2 s minimum interval)

• Zero config, zero API keys

Related MCP server: cnpjaberto

Quick Start

Requirements: Node 18+

git clone https://github.com/davi713albano-coder/mcp-server-brasil.git
cd mcp-server-brasil
npm install
npm run build

The server runs over stdio and is meant to be launched by an MCP client -- not manually.

MCP Integration

Claude Desktop

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "brasil": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-brasil/dist/index.js"]
    }
  }
}

Or via npx (once published to npm):

{
  "mcpServers": {
    "brasil": {
      "command": "npx",
      "args": ["mcp-server-brasil"]
    }
  }
}

Restart Claude Desktop after editing.

Cursor

Add to .cursor/mcp.json in your project or global config:

{
  "mcpServers": {
    "brasil": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-brasil/dist/index.js"]
    }
  }
}

Windsurf / Other MCP Clients

Any client that supports the MCP stdio transport can launch the server the same way. Point the command at node and the first arg at dist/index.js.

API Reference

consulta_cnpj

Looks up a Brazilian company by its CNPJ registration number.

Parameters:

Example request:

{
  "cnpj": "00.000.000/0001-91"
}

Example response:

{
  "cnpj": "00.000.000/0001-91",
  "razao_social": "EMPRESA EXEMPLO LTDA",
  "nome_fantasia": "EXEMPLO",
  "situacao": "ATIVA",
  "data_abertura": "01/01/2000",
  "natureza_juridica": "Ltda",
  "capital_social": "1000000.00",
  "atividade_principal": "Comercio de Exemplo",
  "endereco": {
    "logradouro": "Rua Exemplo",
    "numero": "123",
    "complemento": "Sala 4",
    "bairro": "Centro",
    "cidade": "Sao Paulo",
    "estado": "SP",
    "cep": "01000-000"
  },
  "telefone": "(11) 0000-0000",
  "email": "contato@exemplo.com",
  "sociedades": [
    { "nome": "Joao Silva", "qualificacao": "Socio-Administrador" }
  ],
  "ultima_atualizacao": "01/01/2024"
}

consulta_cep

Looks up a Brazilian postal code (CEP) and returns the associated address.

Parameters:

Example request:

{
  "cep": "01001-000"
}

Example response:

{
  "cep": "01001-000",
  "logradouro": "Praca da Se",
  "complemento": "lado impar",
  "bairro": "Se",
  "cidade": "Sao Paulo",
  "estado": "Sao Paulo",
  "uf": "SP",
  "ibge": "3550308",
  "ddd": "11"
}

cotacao_dolar

Returns the latest USD/BRL and EUR/BRL exchange rates. No parameters required.

Example response:

{
  "dolar": {
    "moeda": "USD/BRL",
    "compra": 5.05,
    "venda": 5.06,
    "alta": 5.11,
    "baixa": 5.04,
    "variacao": -0.47,
    "atualizado_em": "01/01/2024, 15:30:00"
  },
  "euro": {
    "moeda": "EUR/BRL",
    "compra": 5.45,
    "venda": 5.46,
    "alta": 5.51,
    "baixa": 5.45,
    "variacao": 0.12,
    "atualizado_em": "01/01/2024, 15:30:00"
  }
}

Configuration

No environment variables or API keys are needed. The server uses free public APIs:

Development

# install dependencies
npm install

# build TypeScript
npm run build

# watch mode
npm run dev

Roadmap

• CPF lookup (with proper authentication)

• Vehicle plate lookup (SINESP API)

• Docker image for easy deployment

• Unit tests

• TTL-based cache eviction

• npm publish for npx support

Contributing

PRs are welcome. To add a new API tool:

1. Create src/your-tool.ts with valida and consultar exports

2. Register it in src/index.ts inside the TOOLS array and the switch handler

3. Open a PR with a clear description of the tool and its upstream API

License

MIT