# mcp-server-brasil

[![npm version](https://img.shields.io/npm/v/mcp-server-brasil.svg)](https://www.npmjs.com/package/mcp-server-brasil)
[![license](https://img.shields.io/github/license/davi713albano-coder/mcp-server-brasil)](./LICENSE)
[![node](https://img.shields.io/node/v/mcp-server-brasil.svg)](https://nodejs.org/)
[![MCP](https://img.shields.io/badge/MCP-1.0.4-blue)](https://modelcontextprotocol.io)

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+

```bash
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` |

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

Or via npx (once published to npm):

```json
{
  "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:

```json
{
  "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:**

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

**Example response:**

```json
{
  "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:**

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

**Example request:**

```json
{
  "cep": "01001-000"
}
```

**Example response:**

```json
{
  "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:**

```json
{
  "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](https://receitaws.com.br/) | 3 requests / min (free tier). The server auto-throttles to 2 s between calls and caches results in memory. |
| `consulta_cep` | [ViaCEP](https://viacep.com.br/) | Generous; results are cached in memory |
| `cotacao_dolar` | [AwesomeAPI](https://docs.awesomeapi.com.br/) | 20 requests / min (free); results are not cached (live rates) |

---

## Development

```bash
# 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](./LICENSE)