Geocoding Tool

Convierte nombres de ciudades y ubicaciones en coordenadas de latitud y longitud utilizando la API gratuita OpenStreetMap Nominatim. No se requiere clave API.

GitHub
5

Documentación

Servidor MCP de Geocodificación

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona coordenadas de latitud/longitud para ciudades y ubicaciones utilizando la API de OpenStreetMap Nominatim.

Características

  • 🌍 Geocodificación Global: Obtén coordenadas para cualquier ubicación en todo el mundo
  • 🆓 API Gratuita: Utiliza OpenStreetMap Nominatim (no se requiere clave API)
  • Integración MCP: Funciona con Cursor, VS Code, Claude Desktop y otras herramientas compatibles con MCP
  • 📦 Instalación Fácil: Instala vía PyPI con uvx geocode-mcp -️ Herramientas Modernas: Construido con Python 3.12+, async/await y pruebas exhaustivas

Inicio Rápido

Instalación

Instala el paquete desde PyPI usando uvx (recomendado):

uvx geocode-mcp

O instala con pip:

pip install geocode-mcp

Configuración MCP

Añade a la configuración de tu cliente MCP:

{
  "mcpServers": {
    "geocoding": {
      "command": "uvx",
      "args": ["geocode-mcp"]
    }
  }
}

Consulta el directorio config/ para ver ejemplos específicos para diferentes herramientas.

Herramientas Disponibles

mcp_geocoding_get_coordinates

Obtén coordenadas de latitud y longitud para una ciudad o ubicación.

Parámetros:

  • location (obligatorio): Nombre de ciudad, dirección o ubicación (ej., "Nueva York", "París, Francia", "123 Calle Principal, Seattle")
  • limit (opcional): Número máximo de resultados a devolver (predeterminado: 1, máximo: 10)

Ejemplo de Uso:

Get coordinates for Tokyo, Japan
Find the latitude and longitude of London, UK  
What are the coordinates for New York City?
Get coordinates for "1600 Pennsylvania Avenue, Washington DC" with limit 5

Formato de Respuesta:

{
  "query": "Tokyo, Japan",
  "results_count": 1,
  "coordinates": [
    {
      "latitude": 35.6762,
      "longitude": 139.6503,
      "display_name": "Tokyo, Japan",
      "place_id": "282885117",
      "type": "city",
      "class": "place",
      "importance": 0.9,
      "bounding_box": {
        "south": 35.619,
        "north": 35.739,
        "west": 139.619,
        "east": 139.682
      }
    }
  ]
}

Guías de Integración

Cursor

Copia la configuración de config/cursor-mcp.json a la configuración MCP de tu Cursor.

VS Code

Copia la configuración de config/vscode-mcp.json a la configuración MCP de tu VS Code.

Claude Desktop

Copia la configuración de config/claude-desktop.json al archivo de configuración de tu Claude Desktop.

Consulta el README de configuración para instrucciones detalladas de instalación.

Desarrollo

Configuración

# Clone the repository
git clone https://github.com/X-McKay/geocode-mcp.git
cd geocode-mcp

# Install with development dependencies
pip install -e ".[dev]"

Ejecutar Pruebas

# Run all tests
pytest

# Run with coverage
pytest --cov=src/geocode_mcp --cov-report=html

# Run specific test files
pytest tests/test_geocoding.py -v
pytest tests/test_mcp_server.py -v

Calidad de Código

# Format code
ruff format

# Lint code
ruff check

# Run all checks
ruff check && ruff format --check

Desarrollo Local

Para desarrollo y pruebas locales, puedes ejecutar el servidor directamente:

python -m geocode_mcp.server

O usa la configuración de desarrollo en tu cliente MCP:

{
  "mcpServers": {
    "geocoding": {
      "command": "python",
      "args": ["-m", "geocode_mcp.server"],
      "cwd": "/path/to/geocode-mcp",
      "env": {
        "PYTHONPATH": "/path/to/geocode-mcp/src"
      }
    }
  }
}

Estructura del Proyecto

geocode-mcp/
├── src/geocode_mcp/       # Main source code
│   └── server.py          # MCP server implementation
├── tests/                 # Test suite
│   ├── test_geocoding.py  # Geocoding functionality tests
│   ├── test_mcp_server.py # MCP server integration tests
│   ├── test_mcp.py        # MCP protocol tests
│   └── test_vscode.py     # VS Code integration tests
├── config/                # Configuration examples
│   ├── cursor-mcp.json    # Cursor configuration
│   ├── vscode-mcp.json    # VS Code configuration
│   ├── claude-desktop.json # Claude Desktop configuration
│   └── README.md          # Configuration guide
├── docs/                  # Documentation
├── pyproject.toml         # Project configuration
├── requirements.txt       # Production dependencies
├── requirements-dev.txt   # Development dependencies
└── README.md             # This file

Referencia de la API

Funciones Principales

async def geocode_location(location: str, limit: int = 1) -> dict[str, Any]:
    """
    Geocode a location using OpenStreetMap Nominatim API.
    
    Args:
        location: The location to geocode
        limit: Maximum number of results (1-10)
        
    Returns:
        Dictionary containing query, results_count, and coordinates
    """

Servidor MCP

El servidor implementa el Protocolo de Contexto de Modelo y proporciona la herramienta mcp_geocoding_get_coordinates para su uso en aplicaciones compatibles con MCP.

Contribuciones

  1. Haz un fork del repositorio
  2. Crea una rama de características (git checkout -b feature/amazing-feature)
  3. Realiza tus cambios
  4. Ejecuta las pruebas (pytest)
  5. Ejecuta el linting (ruff check && ruff format)
  6. Confirma tus cambios (git commit -m 'Add amazing feature')
  7. Sube a la rama (git push origin feature/amazing-feature)
  8. Abre una Solicitud de Extracción

Consulta CONTRIBUTING.md para más detalles.

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.

Agradecimientos

  • OpenStreetMap por proporcionar el servicio gratuito de geocodificación Nominatim
  • Protocolo de Contexto de Modelo por la especificación del protocolo
  • El equipo del SDK MCP de Python por las excelentes herramientas haz lint

Formatea el código

haz format

Verificación de tipos

haz type-check

Ejecuta todas las verificaciones

haz check-all


### Testing

```bash
# Run all tests
make test

# Run with coverage
make test-cov

# Run specific test categories
pytest tests/test_geocoding.py -v  # Geocoding tests
pytest tests/test_mcp.py -v        # MCP server tests
python tests/test_mcp_server.py    # Integration tests
python tests/test_vscode.py        # VSCode tests

Instalación

# Install production dependencies
make install

# Install development dependencies
make install-dev

Configuración

Integración con Cursor

Consulta la Guía de Integración con Cursor para instrucciones detalladas de configuración.

Integración con VSCode

Ejecuta las pruebas de integración de VSCode:

python tests/test_vscode.py

Referencia de la API

Función de Geocodificación

async def geocode_location(location: str, limit: int = 1) -> dict[str, Any]:
    """Geocode a location using Nominatim API."""

Servidor MCP

El servidor proporciona la herramienta get_coordinates que se puede llamar mediante el protocolo MCP.

Contribuciones

  1. Haz un fork del repositorio
  2. Crea una rama de características
  3. Realiza tus cambios
  4. Ejecuta las pruebas: make test
  5. Ejecuta el linting: make lint
  6. Envía una solicitud de extracción

Consulta CONTRIBUTING.md para más detalles.

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.

Agradecimientos

  • OpenStreetMap por proporcionar el servicio de geocodificación Nominatim
  • MCP por la especificación del protocolo

---

## 🚀 Quick Setup Instructions

1. **Create Project Folder:**
   ```bash
   mkdir mcp-geocoding-server-python
   cd mcp-geocoding-server-python

  1. Copia los Archivos: Copia cada sección de archivo de arriba en archivos con los nombres respectivos

  2. Instala las Dependencias:

    pip install -r requirements.txt

  3. Ejecuta el Servidor:

    python geocoding_server.py

  4. Configura el Cliente MCP: Añade a la configuración de tu cliente MCP (como Claude Desktop):

    {
  "mcpServers": {
    "geocoding": {
      "command": "python",
      "args": ["/full/path/to/mcp-geocoding-server-python/geocoding_server.py"]
    }
  }
}