Server Brasil

npm version license node MCP

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

Tool	Source	What it returns
consulta_cnpj	ReceitaWS	Company name, trade name, status, capital, address, partners
consulta_cep	ViaCEP	Street, neighborhood, city, state, IBGE code, area code
cotacao_dolar	AwesomeAPI	Bid/ask, high/low, daily variation for USD and EUR

• 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

---

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:

OS	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\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:

Name	Type	Required	Description
cnpj	string	Yes	14-digit CNPJ, with or without punctuation

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": "[email protected]",
  "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:

Name	Type	Required	Description
cep	string	Yes	8-digit CEP, with or without hyphen

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:

Tool	Upstream API	Rate limit
consulta_cnpj	ReceitaWS	3 requests / min (free tier). The server auto-throttles to 2 s between calls and caches results in memory.
consulta_cep	ViaCEP	Generous; results are cached in memory
cotacao_dolar	AwesomeAPI	20 requests / min (free); results are not cached (live rates)

---

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