Skip to main content
Glama

MCP-CEP

MCP server for querying ZIP codes using the ViaCEP public API.
Compatible with Goose as a Command-line Extension.


👤 Author

Wendell Barreto
https://github.com/wendellbigato


🚀 Installation

1. Clone this repository

git clone https://github.com/wendellbigato/mcp-cep.git
cd mcp-cep

Please change the above URL to the real one when posting.


2. Create and activate the virtual environment

python3.11 -m venv .venv
source .venv/bin/activate  # Linux/macOS
# ou
.venv\Scripts\activate.bat  # Windows

3. Install dependencies with uv or pip

Using uv :

uv pip install -e ".[cli]"

Or with normal pip:

pip install -e ".[cli]"

Related MCP server: cep-tools

🧩 Setting up as an extension in Goose

  1. Execute:

goose configure
  1. Select Add Extension

  2. Choose Command-line Extension

  3. Fill in the fields:

Field

Value

Extension name

mcp-cep

Command to run

/caminho/completo/para/uv --directory /caminho/para/mcp-cep run main.py

Timeout

300

Environment

(blank, or customize if needed)

Use which uv and pwd to find the correct paths.


✅ How to test on Goose

After setting up, start:

goose session --with-extension mcp-cep

And send commands like:

Repita: Olá!
Qual o endereço do CEP 01001000?

🧰 Available tools

  • echo(texto: str) : repeats the sent text.

  • buscar_cep(cep: str) : query address information via ViaCEP.


📄 License

This project is licensed under the MIT License.

Available Tools

3 tools
buscar_cepB

Consulta informações de um CEP brasileiro usando a API ViaCEP.

Args:
    cep: Código de Endereçamento Postal no formato 01001000 ou 01001-000.

Returns:
    Um dicionário com informações de endereço como rua, bairro, cidade e estado.

Inputs: cep (required).

buscar_ceps_por_logradouroA

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.

Inputs: uf (required), cidade (required), logradouro (required).

echoB

Repete o texto enviado.

Inputs: texto (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 3 tools

    Disambiguation4/5

    The first two tools have clearly distinct purposes: buscar_cep queries by CEP number, while buscar_ceps_por_logradouro queries by address components. However, the echo tool is completely unrelated to the CEP domain, creating a minor ambiguity about the server's primary focus. The core CEP tools are well-differentiated.

    Naming Consistency3/5

    Two tools follow a consistent Portuguese verb_noun pattern (buscar_cep, buscar_ceps_por_logradouro), but the third tool (echo) breaks this pattern with an English name. The naming is readable but lacks full consistency across the set due to the language and pattern mismatch.

    Tool Count3/5

    Three tools is borderline for a CEP server. While the two core CEP tools provide basic lookup functionality, the inclusion of an unrelated echo tool makes the count feel artificially inflated. For a focused CEP service, 2-4 domain-specific tools would be more appropriate.

    Completeness3/5

    The server covers the essential CEP lookup operations: query by CEP and query by address components. However, there are notable gaps for a complete CEP service - no tools for address validation, reverse geocoding, or handling CEP ranges. The echo tool adds no value to the CEP domain coverage.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that enables querying detailed address information from Brazilian postal codes (CEPs) via the ViaCEP API, returning data such as street names, neighborhoods, cities, states, regions, and IBGE codes.
      2
      1
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables querying Brazilian CEP (postal code) addresses via the public ViaCEP API, returning formatted HTML with address details.
      GPL 3.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for querying Brazilian postal codes (CEP) from the official Correios source, supporting read-only lookups via natural language in any MCP-compatible client.
      MIT