Available Tools
The MCP server exposes 15 tools across four categories, plus two resources for discovery. Every tool is a thin wrapper over a corresponding maps.guru/api/v1/* endpoint — whatever your API key is scoped for, the tool can do.
Geocoding Tools
geocode
Convert an address or place name to geographic coordinates.
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Address or place name to geocode |
language | string | No | Response language (e.g., en, fr, de) |
limit | number | No | Max results (1-10, default: 5) |
bbox | string | No | Bounding box to bias results (minLon,minLat,maxLon,maxLat) |
Example prompt: "Geocode '1600 Pennsylvania Avenue, Washington DC'"
reverse_geocode
Convert coordinates to a human-readable address.
| Parameter | Type | Required | Description |
|---|---|---|---|
lat | number | Yes | Latitude (-90 to 90) |
lng | number | Yes | Longitude (-180 to 180) |
language | string | No | Response language |
Example prompt: "What's at coordinates 48.8566, 2.3522?"
autocomplete
Get place search suggestions as the user types.
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Partial search text |
language | string | No | Response language |
limit | number | No | Max suggestions (1-10, default: 5) |
bbox | string | No | Bounding box bias |
Example prompt: "Search for places matching 'Eiffel'"
Map Integration / GIS Export Tools
get_tile_url
Get the XYZ tile URL for a map style, including a QGIS-ready connection URI.
| Parameter | Type | Required | Description |
|---|---|---|---|
style_slug | string | Yes | Style identifier (e.g., city-streets) |
Returns:
{
"tile_url": "https://tiles.maps.guru/v1/planet-vector/{z}/{x}/{y}.pbf?key=mapx_xxx",
"qgis_uri": "type=xyz&url=https://tiles.maps.guru/v1/...&zmax=14&zmin=0",
"style_url": "https://maps.guru/api/v1/styles/public/city-streets/style.json?key=mapx_xxx"
}
Example prompt: "Get the tile URL for my city-streets style"
get_style_json
Fetch the complete MapLibre style JSON with API keys injected into all URLs.
| Parameter | Type | Required | Description |
|---|---|---|---|
style_id | string | Yes | Style ID or slug |
Example prompt: "Export the full style.json for my dark-theme map"
get_static_map
Generate a static map image. Returns both a public URL and inline base64 image.
| Parameter | Type | Required | Description |
|---|---|---|---|
style_slug | string | Yes | Style identifier |
lat | number | Yes | Center latitude |
lng | number | Yes | Center longitude |
zoom | number | Yes | Zoom level (0-22) |
width | number | No | Image width in px (default: 800) |
height | number | No | Image height in px (default: 600) |
Example prompt: "Generate a 1200x800 map image of Paris at zoom 12"
get_dataset_geojson
Export a user-uploaded dataset as GeoJSON. The result can be loaded directly into QGIS, ArcGIS, or any GIS tool.
| Parameter | Type | Required | Description |
|---|---|---|---|
dataset_id | string | Yes | Dataset identifier |
Example prompt: "Export my earthquake dataset as GeoJSON"
Style Management Tools
list_styles
List all map styles in the user's account with metadata.
No parameters required.
Example prompt: "Show me all my map styles"
create_style
Create a new map style from a preset template.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Style name |
preset | string | Yes | Preset template (light, dark, satellite, 3d_dawn, etc.) |
Example prompt: "Create a new dark-themed map style called 'Night Mode'"
modify_style_ai
Modify an existing map style using natural language instructions.
| Parameter | Type | Required | Description |
|---|---|---|---|
style_id | string | Yes | Style to modify |
instructions | string | Yes | Natural language modification instructions |
Example prompt: "Make the water darker blue and hide all road labels on my city-streets style"
share_style
Make a map style publicly accessible and generate a shareable URL.
| Parameter | Type | Required | Description |
|---|---|---|---|
style_id | string | Yes | Style to share |
Example prompt: "Share my city-streets style publicly"
brand_style
Generate a map style that matches a website's brand colors using Vision AI.
| Parameter | Type | Required | Description |
|---|---|---|---|
website_url | string | Yes | Website URL to extract brand colors from |
Example prompt: "Create a map style matching the Stripe website brand"
Data & Account Tools
list_datasets
List datasets attached to a specific map style.
| Parameter | Type | Required | Description |
|---|---|---|---|
style_id | string | Yes | Style to list datasets for |
Example prompt: "What datasets are on my city-streets style?"
get_usage
Check current API usage and quota status for the active organization.
No parameters required.
Example prompt: "How many API calls have I used this month?"
place_lookup
Get detailed information about a specific place by its identifier.
| Parameter | Type | Required | Description |
|---|---|---|---|
place_id | string | Yes | Place identifier from geocoding results |
Example prompt: "Get details for this place ID from my geocoding results"
Resources
style-presets (mapsguru://presets)
Returns the list of available map style presets that can be used with create_style.
service-info (mapsguru://info)
Returns API capabilities, supported services, rate limits, and subscription tier information.
Tool annotations
Every tool ships with MCP annotations so the client can reason about its behavior:
| Annotation | Tools | Meaning |
|---|---|---|
readOnlyHint: true | Geocoding, GIS export, data queries | Doesn't modify state |
idempotentHint: true | All read-only tools | Safe to retry |
destructiveHint: false | Style creation, sharing | Modifies state but not destructively |
openWorldHint: true | Geocoding, brand_style | Hits external web data |