buscar_ceps_por_logradouro
Find Brazilian postal codes (CEPs) by street name in a specific city and state. Use this tool to locate all postal codes associated with a particular address.
Instructions
Busca todos os CEPs associados a um logradouro em uma cidade e estado.
Args:
uf: Sigla do estado (ex: SP, RJ)
cidade: Nome da cidade (ex: São Paulo)
logradouro: Nome da rua, avenida, praça etc (ex: Praça da Sé)
Returns:
Lista de dicionários com endereços que correspondem à busca.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| uf | Yes | ||
| cidade | Yes | ||
| logradouro | Yes |
Implementation Reference
- cep.py:33-55 (handler)The main handler function for the 'buscar_ceps_por_logradouro' tool. It queries the ViaCEP API with the provided state (uf), city (cidade), and street (logradouro) to retrieve a list of matching CEPs and addresses. Includes error handling for API failures and invalid addresses. The @mcp.tool() decorator registers it as an MCP tool.@mcp.tool() async def buscar_ceps_por_logradouro(uf: str, cidade: str, logradouro: str) -> list: """Busca todos os CEPs associados a um logradouro em uma cidade e estado. Args: uf: Sigla do estado (ex: SP, RJ) cidade: Nome da cidade (ex: São Paulo) logradouro: Nome da rua, avenida, praça etc (ex: Praça da Sé) Returns: Lista de dicionários com endereços que correspondem à busca. """ url = f"https://viacep.com.br/ws/{uf}/{cidade}/{logradouro}/json/" try: async with httpx.AsyncClient(timeout=10.0) as client: response = await client.get(url) response.raise_for_status() data = response.json() if isinstance(data, dict) and "erro" in data: return [{"erro": "Endereço não encontrado."}] return data except Exception as e: return [{"erro": f"Erro ao buscar logradouro: {str(e)}"}]