Labsco
X-McKay logo

Geocoding Tool

โ˜… 5

from X-McKay

Convert city names and locations into latitude and longitude coordinates using the free OpenStreetMap Nominatim API. No API key is required.

๐Ÿ”ฅ๐Ÿ”ฅ๐Ÿ”ฅโœ“ VerifiedFreeAdvanced setup
#documents#git#maps

Geocode MCP Server

A Model Context Protocol (MCP) server that provides latitude/longitude coordinates for cities and locations using the OpenStreetMap Nominatim API.

Features

  • ๐ŸŒ Global Geocoding: Get coordinates for any location worldwide
  • ๐Ÿ†“ Free API: Uses OpenStreetMap Nominatim (no API key required)
  • ๏ฟฝ MCP Integration: Works with Cursor, VS Code, Claude Desktop, and other MCP-compatible tools
  • ๐Ÿ“ฆ Easy Installation: Install via PyPI with uvx geocode-mcp
  • ๏ฟฝ๏ธ Modern Tooling: Built with Python 3.12+, async/await, and comprehensive testing

Available Tools

mcp_geocoding_get_coordinates

Get latitude and longitude coordinates for a city or location.

Parameters:

  • location (required): City name, address, or location (e.g., "New York", "Paris, France", "123 Main St, Seattle")
  • limit (optional): Maximum number of results to return (default: 1, max: 10)

Example Usage:

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

Response Format:

{
  "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
      }
    }
  ]
}

Integration Guides

Cursor

Copy the configuration from config/cursor-mcp.json to your Cursor MCP settings.

VS Code

Copy the configuration from config/vscode-mcp.json to your VS Code MCP settings.

Claude Desktop

Copy the configuration from config/claude-desktop.json to your Claude Desktop config file.

See the config README for detailed setup instructions.

Development

Setup

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

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

Running Tests

# 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

Code Quality

# Format code
ruff format

# Lint code
ruff check

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

Local Development

For local development and testing, you can run the server directly:

python -m geocode_mcp.server

Or use the development configuration in your MCP client:

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

Project Structure

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

API Reference

Core Functions

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
    """

MCP Server

The server implements the Model Context Protocol and provides the mcp_geocoding_get_coordinates tool for use in MCP-compatible applications.

API Reference

Geocoding Function

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

MCP Server

The server provides the get_coordinates tool that can be called via the MCP protocol.