atlasfetch-mcp
OfficialProvides reverse geocoding to administrative boundaries and geofencing using boundary data derived from OpenStreetMap, returning country, region, and municipality with ISO codes.
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., "@atlasfetch-mcpwhich municipality is -33.9249, 18.4241 in?"
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.
atlasfetch-mcp
No signup needed to try it: without a key it falls back to a shared public demo key, capped at 1,000 lookups a month across everyone using it. Get your own limits with a free sign-up at atlasfetch.xyz.
An MCP server for AtlasFetch — reverse geocoding to administrative boundaries, and geofencing, as tools your AI assistant can call directly.
Ask "which municipality is -33.9249, 18.4241 in?" and get Cape Town, Western Cape, South Africa with ISO 3166 codes — from a real point-in-polygon lookup, not the model's memory.
country: United Kingdom (GB) · region: England (GB-ENG) · municipal: City of Westminster (GB-WSM)What it does
Tool | What it does |
| A coordinate becomes the country, region and municipality containing it, with ISO 3166-1 / 3166-2 codes, plus matches from your own boundary sets. Optionally returns the point as an H3 cell or Google Plus Code. |
| Lists your boundary sets, their counts, and which API keys may query them. |
| Creates an empty set for your own polygons. |
| Adds one GeoJSON polygon, with properties returned on every match. |
Good for: reverse geocoding to administrative areas, geofencing against your own delivery zones or service areas, jurisdiction and region checks, tagging location data with region codes.
Not for: street addresses or postcodes (this is not forward geocoding — results stop at the municipality), routing, distances, map tiles, or downloading boundary geometry.
Related MCP server: Location MCP Server
Install
Claude Code
claude mcp add atlasfetch -- npx -y atlasfetch-mcpClaude Desktop, Cursor, VS Code and other clients
Add to your MCP config (claude_desktop_config.json, .cursor/mcp.json, or your client's equivalent):
{
"mcpServers": {
"atlasfetch": {
"command": "npx",
"args": ["-y", "atlasfetch-mcp"],
"env": {
"ATLASFETCH_API_KEY": "your-key-here"
}
}
}
}Requires Node 20 or newer.
Getting a key
The demo key is shared by every anonymous user on the internet — one pooled quota and rate limit. Fine for a first look, wrong for anything real.
Create your own at atlasfetch.xyz/dashboard and set ATLASFETCH_API_KEY. The free Personal plan needs no card.
Variable | Default | Purpose |
| (demo key) | Your API key. |
|
| Override only for local or staging APIs. |
Two things that surprise people
municipal is the finest unit available, not a consistent kind of thing. Los Angeles returns a city; rural Kansas returns a county; some places return a district. Where a country's fine tier is patchy, a coarser complete tier answers instead, because a county beats null for most uses. Don't assume the value names a city.
A new boundary set cannot be made queryable from here. Sets are created switched off and granted to no key, and granting is addressed by API key id — which only a signed-in browser session can list. So this server can create a set and fill it, but the last step happens in the dashboard. create_boundary_set says so in its response rather than leaving you with a set that silently matches nothing.
Billing
One call is one lookup, however many layers, sets or grid codes it touches. Metering happens before matching, so a lookup that matches nothing still counts. Requests rejected as invalid or rate-limited are not billed.
Development
npm install
npm run build
node scripts/smoke.mjs # drives the built server with a real MCP client, against the live APILinks
Playground — try a lookup with no signup
Licence
MIT for this server. Reference boundaries derive from OpenStreetMap under the ODbL; attribution and share-alike obligations pass through to you. Coordinates you look up are not stored.
Available Tools
4 toolsadd_boundaryAdd a polygon to a boundary setADestructive
Adds ONE polygon to an existing boundary set on this account, so that lookup_location reports when a point falls inside it — delivery zones, service areas, sales territories. Each call creates a new boundary: calling twice with the same name stores two.
Before calling: the set must already exist (create_boundary_set). A set matches nothing in lookups until it is switched on and granted to an API key in the dashboard at https://atlasfetch.xyz/dashboard, which this server cannot do.
geometry must be a single GeoJSON Polygon — not a MultiPolygon, Feature or FeatureCollection. Positions are [longitude, latitude]. Each ring needs at least 4 positions and must be closed (last position equals the first); extra rings are holes. Self-intersecting shapes are rejected. To store a MultiPolygon, add each part separately.
Plan limits cap vertices per polygon (every position counts, including the closing one), properties per boundary and boundaries per set; a limit hit is refused with a message naming it. WITHOUT YOUR OWN KEY, the shared demo key is on the Public plan: at most 5 positions per polygon (a closed quadrilateral), properties only category (zone, area, route, place, other), color (green, blue, red, yellow, purple, orange) and priority (low, medium, high), and one set shared with every demo user, where adding to a full set silently deletes its oldest boundary. Never upload anything private with the demo key.
Returns the stored boundary: id, set, name, properties, pointCount and createdAt.
| Name | Required | Description | Default |
|---|---|---|---|
| set | Yes | Name of an existing set on this account (see list_boundary_sets). | |
| name | Yes | Label returned when a looked-up point falls inside this polygon, e.g. "Zone A". | |
| geometry | Yes | A GeoJSON Polygon, e.g. {"type":"Polygon","coordinates":[[[18.40,-33.93],[18.40,-33.90],[18.44,-33.90],[18.44,-33.93],[18.40,-33.93]]]}. | |
| properties | No | Optional flat key/value pairs returned with every match: keys up to 32 characters, values a string (up to 256 characters), number or boolean. The demo key accepts only category, color and priority, from fixed lists. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description reveals key non-obvious behaviors: calling twice with the same name stores two boundaries, self-intersecting geometries are rejected, plan limits cap vertices/properties/boundaries and produce a refusal message, and a full demo set silently deletes its oldest boundary. This substantially complements the destructiveHint and idempotentHint annotations.
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 long but every paragraph earns its place: purpose, prerequisites, geometry constraints, plan limits, demo-key caveats, and return values. It is front-loaded with the core behavior and organized so an agent can scan the critical constraints quickly.
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?
With no output schema, the description explicitly lists the returned fields: id, set, name, properties, pointCount, and createdAt. It also covers failure modes, plan limits, authentication prerequisites, and the destructive demo-key behavior, making the tool fully callable by an agent without needing external context.
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?
Although the schema coverage is 100%, the description adds meaning the schema alone does not convey: duplicate names are allowed, every position including the closing one counts toward vertex limits, a MultiPolygon must be split into separate calls, and properties are restricted per plan. The geometry constraints and example also reinforce the schema's coordinate-order and closed-ring requirements.
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 names a specific verb ('Adds'), a specific resource ('ONE polygon to an existing boundary set'), and a concrete effect on lookup_location. It clearly distinguishes itself from create_boundary_set by requiring the set to already exist, and from lookup_location by stating it is the tool that makes containment reportable.
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?
Explicit before-calling prerequisites are given: the set must already exist via create_boundary_set, and it must be switched on and granted to an API key in the dashboard. It also gives a clear when-not-to-use instruction for MultiPolygons ('add each part separately') and warns against using the shared demo key for private data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_boundary_setCreate a boundary setA
Creates an empty named set to hold your own polygons: delivery zones, service areas, sales territories.
IMPORTANT, and not a bug: a new set is created unavailable and granted to no key, so it matches nothing until both are changed. Granting is addressed by API key id, and the only endpoint that lists key ids needs a browser session — which this server does not have. So this tool can create the set and add boundaries to it, but CANNOT make it queryable. Tell the user to finish that at https://atlasfetch.xyz/dashboard.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | A short name, used to reference the set in lookups: 1-32 letters, digits, hyphens or underscores, starting with a letter or digit. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint false, openWorldHint true, etc.), the description discloses the critical non-obvious behavior: the new set is unavailable and granted to no key, matches nothing until changed, and cannot be made queryable because the server has no browser session. This is exactly the kind of hidden trait an agent needs.
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 front-loaded with the core purpose and then uses a clearly marked IMPORTANT block for the critical caveat. The warning is a little verbose but every sentence carries necessary information about the limitation and required user follow-up.
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?
For a one-parameter creation tool with no output schema, the description covers the purpose, the hidden behavior, and the required external follow-up. It does not describe the response/return value, but that is not essential enough to drop below a 4 given the rich caveat.
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 input schema already has 100% description coverage for the single `name` parameter, including pattern and length. The tool description adds only the notion of a 'named set' and does not deepen parameter semantics beyond the schema, so a baseline score of 3 is appropriate.
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 opens with a precise verb and object: 'Creates an empty named set to hold your own polygons...' and gives concrete use cases. It is clearly distinct from siblings like list_boundary_sets, lookup_location, and add_boundary, which perform listing, lookup, and adding rather than creation.
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?
It clearly situates the tool as a creation step for polygon sets and warns that this tool cannot make the set queryable, instructing the agent to tell the user to finish at the dashboard. It lacks an explicit 'use X instead' comparison to sibling tools, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_boundary_setsList the boundary sets on this accountARead-only
Lists the boundary sets on this account with their boundary counts and the API keys (id and label) each is granted to. A set only matches during a lookup when it is available AND granted to the key making the call.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds behavioral context beyond annotations: it reveals the response includes boundary counts and granted API keys, and explains the availability/grants condition that affects matching. This is useful, non-redundant information.
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?
Two sentences with no wasted words. The first sentence front-loads the primary purpose and output content; the second adds a crucial behavioral nuance. Every word earns its place.
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?
For a no-parameter listing tool without an output schema, the description is complete. It specifies what the response contains (boundary counts and granted API keys) and explains the matching rule, covering all an agent needs to call it 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 tool has zero parameters, so the baseline for parameter semantics is 4. The description does not need to explain any parameters, and it correctly focuses on behavior and output instead.
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 action (Lists) and resource (boundary sets), and specifies the output includes boundary counts and the API keys (id and label) each is granted to. It distinguishes itself from siblings (create_boundary_set, add_boundary, lookup_location) by focusing on listing existing sets rather than creating or adding.
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 context about how sets match during lookups, implying this tool is for inspecting which sets are available and granted to the calling key. However, it does not explicitly state when to use this tool versus the alternatives, such as 'use lookup_location for actual matching.' The guidance is clear but not prescriptive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
lookup_locationLook up the boundaries containing a coordinateARead-only
Reverse geocode a coordinate to the administrative areas that contain it — country, region (state or province) and municipality — as names plus ISO 3166 codes, and match it against boundary sets the account has uploaded, in the same call.
Use for: which country, region or municipality a point is in; geofence checks against your own polygons; tagging data with region codes. Do NOT use for: street addresses or postcodes (this is not forward geocoding, and results stop at the municipality), routing, distances, or fetching boundary geometry.
Caveats worth repeating to the user: municipal is the finest unit AVAILABLE, not a consistent kind of thing — Los Angeles returns a city, rural Kansas returns a county, so do not assume it names a city. A layer that matched nothing comes back null. The errors array is always present: a boundary set that is unavailable or not granted to this key is skipped and reported there, while the call itself still succeeds.
One call is one billed lookup however many layers, sets or grid codes it touches, and a call that matches nothing still bills.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | Yes | Latitude, -90 to 90. | |
| lng | Yes | Longitude, -180 to 180. | |
| base | No | Which reference layers to resolve. Defaults to all three. | |
| sets | No | Names of the boundary sets on this account to match against. Defaults to none. | |
| h3res | No | H3 resolution 0-15. 9 is about 400 m across. | |
| encode | No | Also return the point as an H3 cell index and/or Google Plus Code. Output only — neither can be used AS a location, because both name areas rather than points. | |
| pluslen | No | Plus Code length. 9 is not a valid length. 10 is about 14 m. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide readOnlyHint=true and openWorldHint=true. The description adds substantial behavioral context: municipal is the finest unit available, non-matching layers return null, the errors array is always present with skipped sets, and the billing behavior ('one billed lookup however many layers...'). These go far beyond the annotations and directly inform how the agent should interpret results and costs.
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 longer than average but every sentence carries information: purpose, use-for, do-not-use-for, caveats, error handling, and billing. It is front-loaded with the core function and uses clear paragraph breaks. A slight reduction would be possible, but there is no fluff or repetition, so it earns a high score.
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?
For a tool with 7 parameters and no output schema, the description is highly complete: it covers usage scope, exclusions, caveats about municipal granularity, null results, the always-present errors array, and billing implications. It does not explicitly describe the JSON response shape beyond 'names plus ISO 3166 codes', which would be helpful, but given that the schema and examples are absent, it still provides enough context for an agent to call it 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?
Schema description coverage is 100%, so all 7 parameters are already documented individually. The description does not add per-parameter detail, but it integrates the parameters conceptually (layers, sets, grid codes) and clarifies that some parameters only affect output encoding. This is adequate but not a significant improvement over the schema, so the baseline of 3 is appropriate.
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 opens with a specific verb and resource — 'Reverse geocode a coordinate ... as names plus ISO 3166 codes, and match it against boundary sets' — and clearly differentiates itself from siblings list_boundary_sets, create_boundary_set, and add_boundary, which are about managing boundary sets rather than geocoding. No ambiguity about what the tool does.
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?
It explicitly lists when to use the tool ('Use for: which country, region or municipality a point is in...') and when not to use it ('Do NOT use for: street addresses or postcodes... routing, distances, or fetching boundary geometry'). The exclusions and the reason ('results stop at the municipality') make the decision boundary unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
2 tool updates
v0.1.4- Changed
add_boundary13 fields changed- removed
Input schema / properties / geometry / additionalPropertiesRemoved value: -{} - changed
Input schema / properties / geometry / descriptionPrevious value: -"GeoJSON geometry, e.g. {\"type\":\"Polygon\",\"coordinates\":[[[lng,lat],...]]}. Longitude comes first. A Feature or FeatureCollection is not accepted."New value: +"A GeoJSON Polygon, e.g. {\"type\":\"Polygon\",\"coordinates\":[[[18.40,-33.93],[18.40,-33.90],[18.44,-33.90],[18.44,-33.93],[18.40,-33.93]]]}." - added
Input schema / properties / geometry / propertiesAdded value: +{ + "coordinates": { + "description": "Rings of [longitude, latitude] positions. The first ring is the outline; any further rings are holes. Each ring is closed: its last position repeats its first.", + "items": { + "items": { + "items": { + "type": "number" + }, + "maxItems": 3, + "minItems": 2, + "type": "array" + }, + "minItems": 4, + "type": "array" + }, + "minItems": 1, + "type": "array" + }, + "type": { + "const": "Polygon", + "type": "string" + } +} - removed
Input schema / properties / geometry / propertyNamesRemoved value: -{ - "type": "string" -} - added
Input schema / properties / geometry / requiredAdded value: +[ + "type", + "coordinates" +] - changed
Input schema / properties / name / descriptionPrevious value: -"A name for this boundary, returned on a match."New value: +"Label returned when a looked-up point falls inside this polygon, e.g. \"Zone A\"." - added
Input schema / properties / properties / additionalProperties / anyOfAdded value: +[ + { + "maxLength": 256, + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } +] - changed
Input schema / properties / properties / descriptionPrevious value: -"Flat key/value pairs returned with every match of this boundary."New value: +"Optional flat key/value pairs returned with every match: keys up to 32 characters, values a string (up to 256 characters), number or boolean. The demo key accepts only category, color and priority, from fixed lists." - added
Input schema / properties / properties / propertyNames / maxLengthAdded value: +32 - changed
Input schema / properties / set / descriptionPrevious value: -"The set to add it to. It must already exist."New value: +"Name of an existing set on this account (see list_boundary_sets)." - removed
Input schema / properties / set / maxLengthRemoved value: -32 - removed
Input schema / properties / set / minLengthRemoved value: -1 - added
Input schema / properties / set / patternAdded value: +"^[a-zA-Z0-9][a-zA-Z0-9_-]{0,31}$"
- Changed
create_boundary_set4 fields changed- changed
Input schema / properties / name / descriptionPrevious value: -"A short name, used to reference the set in lookups."New value: +"A short name, used to reference the set in lookups: 1-32 letters, digits, hyphens or underscores, starting with a letter or digit." - removed
Input schema / properties / name / maxLengthRemoved value: -32 - removed
Input schema / properties / name / minLengthRemoved value: -1 - added
Input schema / properties / name / patternAdded value: +"^[a-zA-Z0-9][a-zA-Z0-9_-]{0,31}$"
4 tool updates
v0.1.2- First observed
add_boundary - First observed
create_boundary_set - First observed
list_boundary_sets - First observed
lookup_location
TDQS
Scored across 4 tools
Each tool targets a distinct operation: listing sets, performing a lookup, creating a set, and adding a polygon. The boundary-set vs boundary distinction is clear from names and descriptions, so an agent is unlikely to select the wrong tool.
All tool names follow a consistent lowercase verb_noun pattern: list_boundary_sets, lookup_location, create_boundary_set, add_boundary. There are no mixed casing or vague verb variations.
Four tools is a well-scoped set for a focused geofencing/reverse-geocoding server. Each tool covers a necessary step in the core workflow without redundant additions.
The set is missing obvious lifecycle operations: boundaries and sets cannot be updated, deleted, or listed individually, and newly created sets cannot be activated or granted to API keys from this server, forcing a manual dashboard step. This leaves agents with a one-way create-and-add workflow and no way to correct mistakes or complete the queryability setup.
Maintenance
Related MCP Connectors
Geocoding, reverse geocoding, and places search for LatLng.
Geocoding, weather forecasts, and timezone lookups
Resolve coordinates against delivery and coverage polygons (geofences).
Geocode, reverse geocode, and run Overpass spatial queries on OpenStreetMap data.
Related MCP Servers
- AlicenseCqualityDmaintenanceEnables geocoding and reverse geocoding operations to convert city names to coordinates and coordinates to location names using the API Ninjas service.2MIT
- AlicenseAqualityDmaintenanceEnables IP address location and latitude/longitude address queries, providing detailed geographic information such as country, province, city, and district.26 npmMIT
- AlicenseAqualityDmaintenanceProvides forward/reverse geocoding, bounding box extraction, nearby places discovery, batch geocoding, route waypoints, and administrative boundary lookup using OpenStreetMap data.10Apache 2.0
- FlicenseNot gradedqualityDmaintenanceEnables fast reverse geocoding and batch reverse geocoding from coordinates, using the Jeleo GeoLocation API.-