Uses GitHub Actions for continuous integration with ESLint for code quality
Requires Node.js runtime (v18.0.0+) to execute the MCP server
Distributed as an npm package (@geocoding-ai/mcp) that can be installed and run via npx
Click on "Deploy 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., "@Geocoding MCP Server find the coordinates for the Eiffel Tower"
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.
This is a Model Context Protocol (MCP) server that provides geocoding services by integrating with the Nominatim API.
Node.js >= 18.0.0
Cursor, Windsurf, Claude Desktop, Trae or another MCP Client
Related MCP server: GeoServer MCP Server
Add this to your Claude Desktop claude_desktop_config.json file. See Claude Desktop MCP docs for more info.
{
"mcpServers": {
"geocoding": {
"command": "npx",
"args": [
"-y",
"@geocoding-ai/mcp"
]
}
}
}Codebase: MIT
Documentation: GPLv2 / Nominatim developer community / Nominatim Manual
Geocoding generates a coordinate from an address.
The search API allows to look up a location from a textual description or address. Nominatim supports structured and free-form search queries. The search query may also contain special phrases which are translated into specific OpenStreetMap (OSM) tags (e.g. Pub => amenity=pub). This can be used to narrow down the kind of objects to be returned. Note: Special phrases are not suitable to query all objects of a certain type in an area. Nominatim will always just return a collection of the best matches.
Input:
query: Free-form string to search for. In this form, the query can be unstructured. Free-form queries are processed first left-to-right and then right-to-left if that fails. Commas are optional, but improve performance by reducing the complexity of the search. The free-form may also contain special phrases to describe the type of place to be returned or a coordinate to search close to a position.
format: Format of the response. One of: xml, json, jsonv2, geojson, geocodejson. Default: jsonv2
addressdetails: When set to 1, include a breakdown of the address into elements. The exact content of the address breakdown depends on the output format.
extratags: When set to 1, the response include any additional information in the result that is available in the Nominatim database.
namedetails: When set to 1, include a full list of names for the result. These may include language variants, older names, references and brand.
countrycodes: Filter that limits the search results to one or more countries. The country code must be the ISO 3166-1alpha2 code of the country. Each place in Nominatim is assigned to one country code based on OSM country boundaries. In rare cases a place may not be in any country at all, for example, when it is in international waters. These places are also excluded when the filter is set.
layer: The layer filter allows to select places by themes. Comma-separated list of: address, poi, railway, natural, manmade address: The address layer contains all places that make up an address: address points with house numbers, streets, inhabited places (suburbs, villages, cities, states etc.) and administrative boundaries. poi: The poi layer selects all point of interest. This includes classic points of interest like restaurants, shops, hotels but also less obvious features like recycling bins, guideposts or benches. railway: The railway layer includes railway infrastructure like tracks. Note that in Nominatim's standard configuration, only very few railway features are imported into the database. natural: The natural layer collects features like rivers, lakes and mountains while the manmade layer functions as a catch-all for features not covered by the other layers. manmade: The manmade layer collects features that are man-made.
featureType: Allows to have a more fine-grained selection for places from the address layer. Results can be restricted to places that make up the 'state', 'country' or 'city' part of an address. A featureType of settlement selects any human inhabited feature from 'state' down to 'neighbourhood'. When featureType is set, then results are automatically restricted to the address layer.
polygon_geojson: Add the full geometry of the place to the result output. Output formats in GeoJSON, KML, SVG or WKT are supported. Only one of these options can be used at a time.
polygon_kml: Add the full geometry of the place to the result output. Output formats in GeoJSON, KML, SVG or WKT are supported. Only one of these options can be used at a time.
polygon_svg: Add the full geometry of the place to the result output. Output formats in GeoJSON, KML, SVG or WKT are supported. Only one of these options can be used at a time.
polygon_text: Add the full geometry of the place to the result output. Output formats in GeoJSON, KML, SVG or WKT are supported. Only one of these options can be used at a time.
polygon_threshold: When one of the polygon_* outputs is chosen, return a simplified version of the output geometry. The parameter describes the tolerance in degrees with which the geometry may differ from the original geometry. Topology is preserved in the geometry.
Output: See https://nominatim.org/release-docs/latest/api/Output/ for the output format.
License: Data © OpenStreetMap contributors, ODbL 1.0. http://osm.org/copyright
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | ||
| format | No | jsonv2 | |
| addressdetails | No | ||
| extratags | No | ||
| namedetails | No | ||
| layer | No | ||
| polygon_geojson | No | ||
| polygon_kml | No | ||
| polygon_svg | No | ||
| polygon_text | No | ||
| polygon_threshold | No | ||
| countrycodes | No | ||
| featureType | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does an excellent job. It discloses behavioral traits such as query processing order (left-to-right then right-to-left), special phrase handling, layer filtering, polygon output options, and license information. There is no contradiction with annotations as none exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections (introduction, input, output, license) and front-loads the main purpose. However, it is overly verbose, particularly in the repeated descriptions for polygon output parameters and the lengthy explanation of special phrases. Some content could be condensed or linked to external documentation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of 13 parameters with no schema descriptions and no output schema, the description is remarkably complete. It explains all input parameters, references external output documentation, and includes usage notes and license. It covers the necessary information for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, but the description compensates thoroughly. Each parameter (q, format, addressdetails, extratags, namedetails, countrycodes, layer, featureType, polygon_*) is explained with its purpose, allowed values, and effects. For example, the 'layer' parameter details what each layer includes. This adds substantial meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Geocoding generates a coordinate from an address.' This is a specific verb+resource pair, and it implicitly differentiates from the sibling 'reverse_geocode' by focusing on address-to-coordinate conversion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool (to look up a location from a textual description or address) and includes detailed notes on query processing and special phrases. However, it does not explicitly state when not to use it or compare with the alternative 'reverse_geocode', missing the highest level of guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reverse geocoding generates an address from a coordinate given as latitude and longitude.
This tool finds the closest suitable OpenStreetMap (OSM) object and returns its address information. The tool uses the Nominatim API to perform the reverse geocoding and returns the address information in a JSON object.
Input:
lat: Latitude of the coordinate in WGS84 projection.
lon: Longitude of the coordinate in WGS84 projection.
zoom: Level of detail required for the address. This is a number that corresponds roughly to the zoom level used in XYZ tile sources in frameworks like Leaflet.js, Openlayers etc. In terms of address details the zoom levels are as follows: 3: country 5: state 8: county 10: city 12: town / borough 13: village / suburb 14: neighbourhood 15: any settlement 16: major streets 17: major and minor streets 18: buildings
format: Format of the response. One of: xml, json, jsonv2, geojson, geocodejson. Default: jsonv2
addressdetails: When set to 1, include a breakdown of the address into elements. The exact content of the address breakdown depends on the output format.
extratags: When set to 1, the response include any additional information in the result that is available in the Nominatim database.
namedetails: When set to 1, include a full list of names for the result. These may include language variants, older names, references and brand.
layer: The layer filter allows to select places by themes. Comma-separated list of: address, poi, railway, natural, manmade address: The address layer contains all places that make up an address: address points with house numbers, streets, inhabited places (suburbs, villages, cities, states etc.) and administrative boundaries. poi: The poi layer selects all point of interest. This includes classic points of interest like restaurants, shops, hotels but also less obvious features like recycling bins, guideposts or benches. railway: The railway layer includes railway infrastructure like tracks. Note that in Nominatim's standard configuration, only very few railway features are imported into the database. natural: The natural layer collects features like rivers, lakes and mountains while the manmade layer functions as a catch-all for features not covered by the other layers. manmade: The manmade layer collects features that are man-made.
polygon_geojson: Add the full geometry of the place to the result output. Output formats in GeoJSON, KML, SVG or WKT are supported. Only one of these options can be used at a time.
polygon_kml: Add the full geometry of the place to the result output. Output formats in GeoJSON, KML, SVG or WKT are supported. Only one of these options can be used at a time.
polygon_svg: Add the full geometry of the place to the result output. Output formats in GeoJSON, KML, SVG or WKT are supported. Only one of these options can be used at a time.
polygon_text: Add the full geometry of the place to the result output. Output formats in GeoJSON, KML, SVG or WKT are supported. Only one of these options can be used at a time.
polygon_threshold: When one of the polygon_* outputs is chosen, return a simplified version of the output geometry. The parameter describes the tolerance in degrees with which the geometry may differ from the original geometry. Topology is preserved in the geometry.
Output: See https://nominatim.org/release-docs/latest/api/Output/ for the output format.
License: Data © OpenStreetMap contributors, ODbL 1.0. http://osm.org/copyright
| Name | Required | Description | Default |
|---|---|---|---|
| lat | Yes | ||
| lon | Yes | ||
| zoom | No | ||
| format | No | jsonv2 | |
| addressdetails | No | ||
| extratags | No | ||
| namedetails | No | ||
| layer | No | ||
| polygon_geojson | No | ||
| polygon_kml | No | ||
| polygon_svg | No | ||
| polygon_text | No | ||
| polygon_threshold | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: it uses the Nominatim API, returns JSON, has license terms, and explains parameter effects including mutual exclusivity of polygon_* parameters. However, it lacks details about response size, rate limits, or error handling, which would enhance transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for input, output, and license. It front-loads the main purpose. However, it is lengthy with detailed zoom level enumeration and could be more concise without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 13 parameters, no annotations, and no output schema, the description covers all aspects: parameter details, usage, and output reference. It provides a link to full output format documentation. Minor gaps like expected return fields or error handling prevent a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description provides rich semantics for all parameters. It defines lat/lon as WGS84, explains zoom levels with a table, lists format options, and describes polygon parameters with mutual exclusivity constraints. This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Reverse geocoding generates an address from a coordinate given as latitude and longitude.' The verb 'generates' and resource 'address' are specific. It distinguishes from the sibling tool 'geocode' by its name and description, making purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided on when to use this tool versus its sibling 'geocode'. The description implies use for coordinate-to-address conversion, but does not state when not to use it or mention alternatives. This omission reduces clarity for an agent choosing between tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
geocodereverse_geocodeScored across 2 tools
The two tools have completely distinct purposes: geocode converts address to coordinates, reverse_geocode does the opposite. There is no overlap or ambiguity.
Both tool names use a clear and consistent verb_noun pattern (geocode, reverse_geocode) with lowercase snake_case, making them predictable.
With only 2 tools, the server is minimal but still adequate for core geocoding needs. It could benefit from additional tools like batch or autocomplete, but the current count is reasonable for a basic service.
The server covers forward and reverse geocoding, which are the essential operations. However, it lacks structured search or batch processing, which are minor gaps that might require workarounds.
MCP server for Japan geodata: cadastral lot numbers (chiban) and reverse geocoding, for AI agents.
Nominatim MCP — wraps OpenStreetMap Nominatim geocoding API (free, no auth)
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
A Model Context Protocol server for Wix AI tools