BAN Geocoding

This MCP server geocodes French addresses by querying the BAN API and returns a standardized address, GPS coordinates, and convenient map links. It helps you quickly convert user-provided addresses into precise location data for mapping, routing, and validation workflows.

How to use

You connect to the BAN Geocoding MCP server from your MCP client. Send a geocoding request containing a French address, and you receive a structured response with the standardized address, latitude, longitude, and links to visualize the location on popular maps.

Typical use cases include live chat assistants, contact record enrichment, and routing scenarios where you need to translate user-provided addresses into exact geographic coordinates. You can test by starting the server locally and sending a test prompt like “Géocode l'adresse 26 avenue André Morizet, Boulogne-Billancourt” to confirm you get a standardized address and coordinates in the results.

How to install

Prerequisites you need before you begin:

• Python 3.12.7 (managed with pyenv).

• uv (a lightweight async server runner). If you do not have uv, install it via your preferred method.

Follow these steps to set up the project locally:

# Install pyenv and UV on macOS (example)
brew install pyenv uv

# Or use the alternative installer method
# curl https://pyenv.run | bash && curl -LsSf https://astral.sh/uv/install.sh | sh

# Create the project and switch to a compatible Python version
mkdir geocode-ban-mcp && cd geocode-ban-mcp
pyenv install 3.12.7 && pyenv local 3.12.7
uv init

# Install dependencies for the MCP
uv add mcp requests

If you prefer Docker, you can build and run the container as an alternative to running locally.

# Build the Docker image
docker build -t geocode-ban-mcp .

# Run the container
docker run -i geocode-ban-mcp

Additional configuration and testing

Configure Claude Desktop to launch the MCP server in either UV-based mode or via Docker. You can add the following entries to Claude Desktop’s configuration to run the MCP server locally from your machine.

{
  "mcpServers": {
    "geocode-ban": {
      "command": "uvx",
      "args": [
        "--directory",
        "/chemin/absolu/vers/geocode-ban-mcp",
        "geocode-ban-mcp"
      ]
    }
  }
}

{
  "mcpServers": {
    "geocode-ban": {
      "command": "docker",
      "args": ["run", "-i", "geocode-ban-mcp"]
    }
  }
}

Tester

Run the test suite to verify the geocoding functionality.

uv run python test_geocode.py

Lancer le serveur en local

Start the server locally to serve requests from your MCP client.

uv run python -m geocode_ban_mcp.server

Utilisation dans Claude

Provide a geocoding prompt to Claude to obtain the results. For example you can type a prompt like the following to geocode a French address.

Géocode l'adresse 26 avenue André Morizet, Boulogne-Billancourt

Expected results include a standardized address, GPS coordinates, and map links suitable for Google Maps and OpenStreetMap.

Notes et ressources

You interact with the BAN API through this MCP server. Use it to enrich data, verify addresses, and provide precise geolocation for downstream applications.

Available tools

geocode

Geocode an address by querying the BAN API and return a standardized address, latitude, longitude, and map links.

test_geocode

Run automated tests to validate the geocoding functionality and ensure accuracy of results.