Provides geocoding capabilities using the OpenStreetMap Nominatim API to get latitude/longitude coordinates and location details for cities, addresses, and places worldwide.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Geocode MCP Serverget coordinates for Paris, France"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-mcpOr install with pip:
pip install geocode-mcpMCP 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 5Response 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 -vCode Quality
# Format code
ruff format
# Lint code
ruff check
# Run all checks
ruff check && ruff format --checkLocal Development
For local development and testing, you can run the server directly:
python -m geocode_mcp.serverOr 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 fileAPI 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 testsInstallation
# Install production dependencies
make install
# Install development dependencies
make install-devConfiguration
Cursor Integration
See Cursor Integration Guide for detailed setup instructions.
VSCode Integration
Run the VSCode integration tests:
python tests/test_vscode.pyAPI 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 testRun linting:
make lintSubmit 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-pythonCopy Files: Copy each file section above into files with the respective names
Install Dependencies:
pip install -r requirements.txtRun the Server:
python geocoding_server.pyConfigure 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"] } } }