buscar_ceps_por_logradouro
Find all Brazilian postal codes (CEPs) associated with a specific street (logradouro) in a given city and state using the MCP-CEP server. Input the state, city, and street name to retrieve matching addresses.
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 |
|---|---|---|---|
| cidade | Yes | ||
| logradouro | Yes | ||
| uf | Yes |
Implementation Reference
- cep.py:34-55 (handler)The main handler function that implements the tool logic: queries the ViaCEP API for CEPs matching the given state (UF), city, and street (logradouro). Handles errors and returns list of address dicts or error.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)}"}]
- cep.py:33-33 (registration)The @mcp.tool() decorator registers the buscar_ceps_por_logradouro function as an MCP tool with FastMCP instance.@mcp.tool()