GeoPy MCP

• Setup
  • Local
  • Remote
• Development
• Building
• Support
• Contributing

MCP Server exposing GeoPy data via the Model Context Protocol.

Setup

This can be run in Local CLI mode or Remote server mode.

Local

In CLI mode using uv.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "geopy": {
      "type": "local",
      "command": ["uvx", "geopy-mcp"],
      "enabled": true
    }
  }
}

In CLI mode using Python pip.

pip install geopy-mcp

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "geopy": {
      "type": "local",
      "command": ["geopy-mcp"],
      "enabled": true
    }
  }
}

Remote

With Docker run.

docker run --rm -p 80:8000 ghcr.io/cssnr/geopy-mcp:latest

With Docker Compose.

services:
  app:
    image: ghcr.io/cssnr/geopy-mcp:latest
    ports:
      - '80:8000'

With Python from source.

uv sync
uv run uvicorn geopy_mcp.server:app --app-dir src --host 0.0.0.0 --port 8000

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "geopy": {
      "type": "remote",
      "url": "http://localhost/mcp",
      "enabled": true
    }
  }
}

For a Docker Swarm + Traefik example see the docker-compose-swarm.yaml.

For a Portainer Deploy workflow see the .github/workflows/deploy.yaml.

Development

Sync project.

uv sync

Run local server.

run cli

Run remote server (live reload).

run dev

Point your client to: http://localhost:8000/mcp

Run remote Docker Compose (live reload).

run compose

Point your client to: http://localhost/mcp

You can set the PORT environment variable.

Building

Docker Image

To build and test the docker image run.

bash build.sh
docker compose up

Point your client to: http://localhost/mcp

Python Package

This builds the bdist and wheel, if you have a use for it...

run build

Support

If you run into any issues or need help getting started, please do one of the following:

• Report an Issue: https://github.com/cssnr/geopy-mcp/issues
• Q&A Discussion: https://github.com/cssnr/geopy-mcp/discussions/categories/q-a
• Request a Feature: https://github.com/cssnr/geopy-mcp/issues/new?template=1-feature.yaml
• Chat with us on Discord: https://discord.gg/wXy6m2X8wY

Contributing

Please consider making a donation to support the development of this project and additional open source projects.

For a full list of current projects visit: https://cssnr.github.io/