MCP-CEP

Provides CEP lookup using the ViaCEP public API via a Goose-extension MCP endpoint.

python

3

GitHub Stars

python

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "wendellbigato-mcp-cep": {
      "command": "uv",
      "args": [
        "--directory",
        "/caminho/para/mcp-cep",
        "run",
        "main.py"
      ]
    }
  }
}

MCP-CEP is an MCP server that lets you look up Brazilian postal codes (CEP) using the ViaCEP public API. It’s designed to be used as a Command-line Extension with Goose, so you can query CEP data directly from your MCP client and automation pipelines.

How to use

You run the MCP server as a local stdio service and connect to it with an MCP client (Goose). Once running, you can fetch address information for a CEP by invoking the buscar_cep function from your MCP client. For example, request data for the CEP 01001000 to retrieve its address details. You can also verify basic responsiveness by using the echo tool to repeat back text you send.

How to install

Prerequisites: Python 3.11 and Git are required to install and run the server.

Clone the project repository.

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

Create and activate a Python virtual environment.

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

Install the dependencies using uv or pip.

uv pip install -e ".[cli]"

pip install -e ".[cli]"

Additional configuration and notes

Configure the MCP server as a local stdio service in Goose to run the Python client extension. Use the following configuration as the stdio entry. This runs the server using uv with a directory pointing to your MCP-CEP code.

{
  "type": "stdio",
  "name": "mcp_cep",
  "command": "uv",
  "args": ["--directory", "/path/to/mcp-cep", "run", "main.py"]
}

Testing and basics

After configuring Goose, start the Goose client and send CEP lookups through the MCP interface. You can test basic functionality by issuing a simple echo check and then a CEP lookup with a known CEP to confirm the response structure and data are correct.

Security and maintenance

Keep your Python environment up to date. If you expose the server to broader networks, ensure proper access controls and limit external access to the Goose client you use for CEP lookups.