How to Use the Nominatim MCP in Windsurf

Geocode addresses and map coordinates directly inside Windsurf. Cascade chains these tools to build location-aware features instantly.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Nominatim MCP to Windsurf

Create your Vinkius account to connect Nominatim to Windsurf and route execution through our secure gateway. The platform manages server hosting, runtime updates, and security layers. Configuration requires no manual server provisioning.

GDPR Free for Subscribers

Setup Nominatim with Windsurf

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Chain Nominatim calls with Cascade

Windsurf allows you to feed raw location data into Cascade for automated processing. You simply define the goal, and the agent uses `search` to resolve addresses into coordinates before piping them into other local development workflows. This removes the need for manual copy-pasting between your browser and editor. Cascade manages the sequence, ensuring each step executes in the correct order without further input.

Verify infrastructure with status tools

Before running complex geocoding tasks, use `get_status` to check if the service is reachable. This prevents your agent from attempting operations when the endpoint is down or hitting latency spikes. You avoid wasted cycles by building this check into your initial setup script. It keeps your development flow moving without unexpected errors interrupting your logic.

Query granular OSM object data

You can pull specific metadata for any node, way, or relation using `lookup_osm` or `get_details`. This is useful when you need to confirm bounding boxes or hierarchy data for specific map features. Cascade handles the parsing of these responses automatically. You get the raw data you need to build accurate UI components or backend logic without writing custom parsers.

Setup guide

Set up Nominatim MCP in Windsurf

Prerequisites

Windsurf IDE installed (macOS, Windows, or Linux)
Active Vinkius subscription with a valid endpoint token

1

Open MCP configuration

Click the Cascade assistant icon in the sidebar, then click the hammer icon (🔨) at the top of the panel. Select "Configure" to open ~/.codeium/windsurf/mcp_config.json.
2

Add the Nominatim MCP

Paste the JSON snippet shown on the right into the mcpServers object. Replace [YOUR_TOKEN_HERE] with your endpoint token from cloud.vinkius.com.
3

Refresh MCPs

Go back to the hammer icon (🔨) in Cascade and click "Refresh". Windsurf will detect the new server. No full restart is needed — the connection is hot-reloaded.
4

Verify in Cascade

Start a new Cascade conversation and ask something like "Show my Nominatim payment history." If connected, Cascade will call the Nominatim tools directly. You will see a green dot next to the server name in the MCP panel.

mcp_config.json

{
  "mcpServers": {
    "nominatim-mcp": {
      "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
    }
  }
}

Get your connection token →

Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by Nominatim. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.

Why Choose Vinkius

Vinkius connects your tools to AI with real-time monitoring and automatic cost savings — all from one dashboard.

Connect Nominatim now

Real-time monitoring

Live

visibility into every interaction

Connect your favorite tools to your AI and see exactly what's happening — every request, every response, in real time.

Built-in savings

60%

lower AI costs

Vinkius compresses data between your apps and your AI automatically. Lower bills every month — no configuration required.

Single dashboard

One

place for every integration

Every tool your AI connects to, managed from a single screen. One account, complete control.

Common questions about Nominatim MCP in Windsurf

Open your MCP panel in Windsurf and ensure the server is active. You can then ask Cascade to search for a specific location, and it will invoke the `search` tool to return the coordinates and address components.

Yes, you can pass latitude and longitude pairs to Cascade. It will use the `reverse_geocode` tool to translate those numbers into a readable address.

Absolutely. You can give Cascade an OSM ID, and it will call `lookup_osm` or `get_details` to fetch the object's properties and bounding box information directly into your context.

This server only interacts with public OpenStreetMap data. It does not store or transmit your personal project files or private user data to third-party endpoints.

The server enforces a rate limit of one request per second. If you automate large batches, you must build in a delay to respect these constraints.

Use it with your favorite AI tools

Connect this server to Cursor, Claude, VS Code, and more.

OpenAI Agents SDK sdk-python

Google ADK sdk-python

Pydantic AI sdk-python