Which integrations are available for this server?

Provides geocoding capabilities using the [OpenStreetMap](/mcp/servers/integrations/openstreetmap) Nominatim API to get latitude/longitude coordinates and location details for cities, addresses, and places worldwide.

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

Quick Start

Installation

Install the package from PyPI using uvx (recommended):

uvx geocode-mcp

Or install with pip:

pip install geocode-mcp

MCP Configuration

Add to your MCP client configuration:

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

See the config/ directory for specific examples for different tools.

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.

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Run tests (pytest)
Run linting (ruff check && ruff format)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

See CONTRIBUTING.md for more details.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

OpenStreetMap for providing the free Nominatim geocoding service
Model Context Protocol for the protocol specification
The Python MCP SDK team for the excellent tooling make lint

Format code

make format

Type check

make type-check

Run all checks

make 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

Installation

# Install production dependencies make install # Install development dependencies make install-dev

Configuration

Cursor Integration

See Cursor Integration Guide for detailed setup instructions.

VSCode Integration

Run the VSCode integration tests:

python tests/test_vscode.py

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.

Contributing

Fork the repository
Create a feature branch
Make your changes
Run tests: make test
Run linting: make lint
Submit a pull request

See CONTRIBUTING.md for more details.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

OpenStreetMap for providing the Nominatim geocoding service
MCP for the protocol specification

--- ## 🚀 Quick Setup Instructions 1. **Create Project Folder:** ```bash mkdir mcp-geocoding-server-python cd mcp-geocoding-server-python

Copy Files: Copy each file section above into files with the respective names
Install Dependencies:
pip install -r requirements.txt
Run the Server:
python geocoding_server.py
Configure MCP Client: Add to your MCP client (like Claude Desktop) configuration:
{ "mcpServers": { "geocoding": { "command": "python", "args": ["/full/path/to/mcp-geocoding-server-python/geocoding_server.py"] } } }

Geocode MCP Server

Features

Quick Start

Installation

MCP Configuration

Available Tools

mcp_geocoding_get_coordinates

Integration Guides

Cursor

VS Code

Claude Desktop

Development

Setup

Running Tests

Code Quality

Local Development

Project Structure

API Reference

Core Functions

MCP Server

Contributing

License

Acknowledgments

Format code

Type check

Run all checks

Installation

Configuration

Cursor Integration

VSCode Integration

API Reference

Geocoding Function

MCP Server

Contributing

License

Acknowledgments

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

`mcp_geocoding_get_coordinates`