Geoapify MCP Server

Connect AI assistants to location data and GeoJSON geometry operations

Geoapify MCP Server is a remote Maps MCP server that gives AI assistants 11 tools for geocoding, place search, routing, route matrices, and GeoJSON geometry operations. It uses the Model Context Protocol or MCP to connect AI tools with real results from Geoapify Maps APIs.

Use it when you want an AI agent to answer location questions with real API results instead of static training data. The tools can look up addresses, discover nearby places, compare travel times, and combine, measure, or transform geometries.

• For AI tools: connect through MCP-compatible clients.
• For location workflows: work with addresses, places, routes, travel times, and GeoJSON geometries.
• For teams: keep access controlled through your Geoapify API key.

Available MCP Tools

Geoapify MCP Server exposes 11 tools for location lookup, routing, and geometry operations. An assistant can discover the tools and their input and output schemas with tools/list, then select the right tool for each task. Results can be used in follow-up searches, planning, and spatial analysis.

For accepted parameters, output schemas, and operation-specific geometry types, see the MCP tool reference and OpenAPI specifications.

Not sure which integration approach fits your application? Read MCP vs. REST APIs for AI applications to compare model-driven tools with direct API calls.

When application code should call Geoapify directly, follow the Geoapify OpenAPI guide for AI coding tools and API clients to import specifications and generate typed integrations.

Getting Started

Connect Geoapify MCP Server to your AI client in two steps:

• Create a Geoapify API key.
• Connect the MCP server to your AI client and start using Geoapify tools.

See the Geoapify MCP documentation for the tool reference and client setup guides.

Authentication

Geoapify MCP Server requires a Geoapify API key. Send it in the x-api-key HTTP header, the authentication method recommended by the OpenAPI specification.

To create a key:

1. Open MyProjects and sign up or sign in.
2. Create a project.
3. Go to API Keys and copy the generated key.

Check the Geoapify Getting Started guide for more details.

Keep the key private. Add it only in your MCP client settings, and do not include it in prompts, public configuration files, or source code.

Endpoints and Client Setup

Use a client that supports remote HTTP or Streamable HTTP MCP connections. Configure one of these endpoints and supply your API key through the client's protected header or secret settings:

Set the x-api-key header to your Geoapify API key. MCP clients normally initialize the connection and discover tools automatically.

For client-specific configuration, follow the Geoapify MCP client setup guide:

• Claude Code: configure the remote HTTP server in .mcp.json, with the API key supplied through an environment variable in the header.
• Cursor: configure the endpoint and header in .cursor/mcp.json, using Cursor's environment-variable syntax.
• ChatGPT: review the guide's authentication compatibility notes and supported integration options before connecting.
• Other clients: use the endpoint and header settings above, then check that Geoapify tools appear in the client's tool list.

Send MCP Requests over HTTP

For a direct integration or connection check, send JSON-RPC request bodies with HTTP POST to the chosen MCP endpoint. Use Content-Type: application/json and x-api-key: YOUR_API_KEY headers. These are MCP protocol requests; their params.arguments fields follow MCP tool schemas.

The supported protocol version is 2025-06-18. The optional MCP-Protocol-Version header defaults to this version when omitted; explicitly unsupported versions are rejected.

Start by initializing the connection:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": {
      "name": "geoapify-example-client",
      "version": "1.0.0"
    }
  }
}

After the initialization response, send the initialized notification. Notifications omit id and receive HTTP 202 with no JSON-RPC response body:

{
  "jsonrpc": "2.0",
  "method": "notifications/initialized"
}

Discover the current tools and their schemas with tools/list:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

To geocode an address, send a tools/call request. The query field is required; country_codes filters the search by country, and limit accepts values from 1 to 10:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "geocode_address",
    "arguments": {
      "query": "601 Eubank Blvd SE, Albuquerque, NM 87123, United States",
      "country_codes": ["us"],
      "limit": 1
    }
  }
}

Example Prompts + Usage Examples

Start with natural-language prompts. The AI assistant can select tools for addresses, nearby places, routes, travel times, and geometry operations. Supply coordinates or GeoJSON when the task depends on a specific location or shape.

Geocode an Address

Tool: geocode_address

Example prompts:

• "Find coordinates for 1000 5th Avenue, New York, NY."
• "Geocode 350 Fifth Avenue, New York, NY and return the formatted address."
• "Find up to 3 possible matches for 1 Market Street, San Francisco."

Geocode a Structured Address

Tool: geocode_structured_address

Provide at least one address field such as street, postcode, city, or country. Pair housenumber with street, and use country_codes for an ISO country-code filter.

Example prompts:

• "Geocode this address: street Market Street, house number 1, city San Francisco, state California, country United States."
• "Find coordinates for postcode SW1A 2AA, city London, country United Kingdom."
• "Find coordinates for this structured address: house number 10, street Downing Street, city London, postcode SW1A 2AA, country United Kingdom."

Reverse Geocode Coordinates

Tool: reverse_geocode_coordinates

Example prompts:

• "What address is located at 48.8584, 2.2945?"
• "Reverse geocode coordinates 40.7484, -73.9857 and return the formatted address."
• "Find the nearest address for latitude 51.5007 and longitude -0.1246."

Discover Place Categories

Tool: list_place_categories

Example prompts:

• "List the place categories I can use to search for restaurants."
• "Which Geoapify place categories are available for healthcare facilities?"
• "Show me the supported categories for public transport places."

Search for Places

Tool: search_places

Example prompts:

• "Find cafés within 1 km of latitude 48.8584 and longitude 2.2945."
• "Find the 10 nearest pharmacies to coordinates 40.7484, -73.9857."
• "Search for tourist attractions near latitude 51.5007 and longitude -0.1246."

The assistant can call list_place_categories with empty arguments to retrieve the category catalog, then choose one exact category for search_places. Place search requires category, lat, and lon; radius_meters is optional. Without a radius, it returns the nearest matching places without a hard distance limit. The result limit can be from 1 to 100.

Calculate a Route

Tool: calculate_route

Provide at least two waypoints, each with named lat and lon values. Set include_instructions: true for turn-by-turn instructions, or geometry_scope: "none" when you only need travel costs. Use optimize_stops: true to reorder intermediate stops while keeping the first and last waypoint fixed.

Example prompts:

• "Calculate a driving route from 48.8584, 2.2945 to 48.8606, 2.3376."
• "Plan a bicycle route between these coordinates and return turn-by-turn instructions."
• "Find a truck route through these three waypoints that avoids tolls."

Calculate a Route Matrix

Tool: calculate_route_matrix

Provide sources and optional targets, using named lat and lon fields. When targets is omitted, the tool uses the source locations as targets too. The number of source-target pairs must not exceed 1,000.

Example prompts:

• "Calculate driving times and distances from these two warehouses to these three delivery locations."
• "Build a walking time matrix for these four coordinates."
• "Compare travel times between all of these locations by bicycle."

Geometry Inputs and Coordinate Order

Geometry tools take GeoJSON Geometry objects, such as Point, LineString, and Polygon. If your data is a Feature, pass its geometry member; a Feature or FeatureCollection is not a geometry input. Each operation accepts specific geometry types, so check its input schema in the MCP documentation.

GeoJSON coordinate arrays use [longitude, latitude]. Reverse geocoding, place search, routing, and matrix tools use named lat and lon fields. When chaining tools, use the geometry object from a returned Feature as the next geometry input.

Combine Geometries

Tool: combine_geometries

Use intersection, difference, or union with 2–100 Polygon or MultiPolygon geometries. For difference, the first polygon is the starting area and later polygons are subtracted from it. Use envelope with 1–100 supported geometries to create a rectangle enclosing them.

Example prompts:

• "Merge these delivery-zone polygons into one service area."
• "Return only the area shared by these two polygons."
• "Subtract this restricted zone from the delivery area."

Evaluate Spatial Relations

Tool: evaluate_spatial_relation

Use contains, crosses, disjoint, intersects, or within to compare geometries. Use valid to check one geometry, or point_on_line to check a Point against a LineString. For comparisons, operand order matters: contains asks whether geometry contains other_geometry.

Example prompts:

• "Check whether this delivery-zone polygon contains the customer's point."
• "Do these two service areas intersect?"
• "Check whether this GeoJSON geometry is valid."

This MCP request uses the polygon and point from the OpenAPI example:

{
  "jsonrpc": "2.0",
  "id": 13,
  "method": "tools/call",
  "params": {
    "name": "evaluate_spatial_relation",
    "arguments": {
      "operation": "contains",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [13.38, 52.5],
            [13.42, 52.5],
            [13.42, 52.54],
            [13.38, 52.54],
            [13.38, 52.5]
          ]
        ]
      },
      "other_geometry": {
        "type": "Point",
        "coordinates": [13.405, 52.52]
      }
    }
  }
}

Measure Geometries

Tool: measure_geometry

Use area for Polygon or MultiPolygon area in square meters, length for line length, or distance for point-to-point distance. Other operations include bbox, point_to_line_distance, point_to_polygon_distance, nearest_point_on_line, and along.

Example prompts:

• "Calculate this service area's size in square meters."
• "Measure the length of this GeoJSON route in kilometers."
• "Find the point on this line nearest to the customer's location."

Distance and length operations accept a units argument and default to kilometers. The area operation returns square meters and does not accept units.

Transform Geometries

Tool: transform_geometry

Use buffer, simplify, rotate, scale, or translate to modify a geometry. Center operations include center (bounding-box center), center_mean, center_median, and center_of_mass.

Example prompts:

• "Create a 500-meter buffer around longitude 13.405, latitude 52.52."
• "Simplify this route geometry while preserving its overall shape."
• "Rotate this polygon clockwise by 30 degrees."

The following MCP request, supplied in the OpenAPI specification, creates a 500-meter buffer around a point:

{
  "jsonrpc": "2.0",
  "id": 22,
  "method": "tools/call",
  "params": {
    "name": "transform_geometry",
    "arguments": {
      "operation": "buffer",
      "geometry": {
        "type": "Point",
        "coordinates": [13.405, 52.52]
      },
      "distance": 500,
      "units": "meters",
      "steps": 16
    }
  }
}

Responses and Errors

A successful tools/call response has result.isError: false. Tool results are available as JSON text in result.content; responses can also provide result.structuredContent for direct processing. The tool's output schema describes the result fields.

Check both the HTTP status and the JSON-RPC body. HTTP 200 alone does not mean a tool succeeded: tool validation and execution failures return result.isError: true. JSON-RPC protocol errors use a top-level error object.

For a validation failure, check the selected tool's required arguments and supported values. MCP tool schemas reject undocumented arguments; REST API parameters should not be copied into a tool call unless that tool's schema defines them. See the OpenAPI specifications for request and response contracts.

API Credits and Rate Limits

Geoapify MCP Server calls Geoapify Maps APIs behind the scenes:

• For example, when an AI assistant uses geocode_address, the MCP server sends a request to the Geoapify Geocoding API.
• Place search, route calculation, and route matrix tools use the Places API, Routing API, and Route Matrix API, respectively.
• The list_place_categories tool requires an API key but costs zero credits.
• Usage and cost are calculated only for the underlying Geoapify Maps API requests.
• The MCP server does not add separate charges, extra credits, or additional rate limits.

Frequently Asked Questions