# Overpass MCP > Overpass MCP Server executes complex spatial queries against OpenStreetMap data. Use this server to find specific points of interest (POIs), extract raw map segments for a bounding box, or check your current API rate limits. It lets your AI agent run deep geospatial analysis using Overpass QL. ## Overview - **Category:** data-analytics - **Price:** Free - **Tags:** openstreetmap, gis, spatial-data, mapping, overpass-ql ## Description **Overpass MCP Server - Querying OSM Data** You don't write complex HTTP calls just to get map data. This server connects your AI agent right into the OpenStreetMap database, letting you run deep geospatial analysis using Overpass QL. It’s built for when you need specific coordinates or raw map segments, and it handles the heavy lifting so you can focus on what you gotta do with the data. **Executing Deep Queries for Specific Features** When you're looking for something precise—say, every single public park or all the bike paths in a neighborhood—you use `execute_query`. This tool runs a full Overpass QL query and spits out the results as structured JSON. You don’t get messy text dumps; you get clean data that your agent can read immediately. It finds specific Points of Interest (POIs), extracts detailed ways, or pulls back relations based on complex criteria you define in your query. This function is how you find all fire stations, utility boxes, or historical markers within a defined area without manually sifting through layers of raw XML. If the features you need are more varied—you gotta pull everything from nodes to ways and relations for an entire region—you'll use `get_map`. This tool fetches every piece of OpenStreetMap data (nodes, ways, and relations) within a specified bounding box. It returns all that info as raw XML, which is what you need if you’re feeding the map into a specialized GIS program or doing deep spatial processing outside of Overpass QL itself. **Handling Legacy Systems and Rate Limits** Sometimes, the system you're talking to hasn't caught up with modern APIs. For those older setups that still use XAPI syntax, you run `execute_xapi`. This tool executes queries written in that older format, giving you raw XML data so your agent doesn't hit a compatibility wall because of outdated API calls. It keeps those legacy systems talking to the latest map data. You gotta watch your usage though; you don’t want your job bombing out halfway through because the rate limit hit zero. You check that with `get_status`. This tool tells you exactly what your current API slot availability is and gives you real-time status on your Overpass account, letting you plan around request throttling when you're running huge datasets or a bunch of consecutive queries. In short, this server lets your agent handle everything from finding structured data sets using modern QL queries to dumping raw XML for GIS processing via `get_map`, and it even manages the housekeeping—checking limits with `get_status` and supporting old XAPI syntax when you need it. You're talking about a complete geospatial toolkit, all running through one connection. ## Tools ### execute_query Runs a full Overpass QL query and returns the results in structured JSON format. ### get_map Fetches all OSM map data (nodes, ways, relations) within a specified bounding box and returns it as raw XML. ### get_status Checks the current API slot availability and rate limit status for your Overpass account. ### execute_xapi Executes a legacy XAPI query, returning raw XML data for older systems. ## Prompt Examples **Prompt:** ``` Use execute_query to find all hospitals within 5km of coordinates 51.5074, -0.1278. ``` **Response:** ``` I've executed the Overpass query. I found 12 hospitals in that radius, including St Thomas' Hospital and Guy's Hospital. Would you like the specific coordinates for any of them? ``` **Prompt:** ``` Get the raw OSM map data for the area 13.3,52.5,13.4,52.6 using get_map. ``` **Response:** ``` I have retrieved the raw XML map data for that bounding box. It contains all nodes, ways, and relations within those coordinates. How would you like me to process this data? ``` **Prompt:** ``` Check my current Overpass API status and rate limits. ``` **Response:** ``` Checking status... You currently have 2 slots available, and no active rate limit cooldowns. You are free to execute more queries. ``` ## Capabilities ### Query for Specific Geographic Features Finds and returns structured data (POIs, ways, relations) from OSM based on a complex Overpass QL query. ### Extract Raw Map XML Data Fetches all node, way, and relation data within specified coordinates into raw XML format for GIS processing. ### Manage API Rate Limits Checks your current usage status to prevent request throttling when running large datasets or multiple queries. ### Run Legacy Queries Executes queries written in the older XAPI syntax for systems that haven't updated their API calls. ## Use Cases ### Mapping all public water sources for a utility project A planner needs to know every cistern and fountain in a neighborhood. They ask their agent: 'Find all fountains within this area.' The agent uses `execute_query` with the specific Overpass QL filter, returning a structured JSON list of coordinates and details for immediate review. ### Building a map visualization from scratch A developer needs the complete raw data dump for an old section of town. They use `get_map` to fetch all nodes, ways, and relations into one XML file. This gives them the foundational layer needed to build their own custom mapping service. ### Running a massive query batch job A research team is running dozens of queries across a large city. Before starting, they first call `get_status` to verify available API slots. This prevents the entire workflow from failing due to unexpected rate limiting. ### Migrating an old system's data calls A team maintains a legacy application that relies on XAPI syntax. Instead of rewriting their code, they instruct their agent to use `execute_xapi`, which processes the query and returns the required raw XML data. ## Benefits - **Deep Feature Extraction:** Use `execute_query` to pinpoint specific features (like schools or bus stops) by writing Overpass QL. You don't have to manually filter massive datasets; the query handles it. - **Full Map Segmentation:** If you need a complete snapshot of an area for specialized GIS processing, `get_map` fetches all raw OSM XML data for a bounding box, ensuring no nodes or ways are missed. - **Predictable Usage:** Never hit a rate limit mid-job. Run `get_status` first to check your remaining API slots and make sure you have capacity before launching large queries. - **Compatibility Layer:** The `execute_xapi` tool lets your agent run against older XAPI syntax, ensuring that legacy applications still get the map data they need without a code rewrite. - **Actionable Data Types:** Results are returned in JSON for structured queries or raw XML/JSON for mapping. Your AI client gets clean output ready for immediate use. ## How It Works The bottom line is: you ask your AI client a question about the physical world, and it gets back the raw map data needed to answer it. 1. First, ensure your AI agent has access to the Overpass API endpoint. You can optionally configure a custom instance URL if needed. 2. Next, tell your agent exactly what you need—for example, 'Find all public swimming pools in downtown Chicago.' 3. The agent calls the appropriate tool (`execute_query`, `get_map`, etc.), runs the query against OSM, and sends back structured data (JSON or XML) based on the result. ## Frequently Asked Questions **How do I find all gas stations using execute_query?** You use `execute_query` and write an Overpass QL query that targets the OSM tag for gas stations. Remember to include the necessary bounding box coordinates in your query parameters. **What is the difference between get_map and execute_query?** `execute_query` returns filtered, structured data (e.g., just hospitals). `get_map` returns every single node, way, and relation in raw XML for a given area, regardless of what they are. **Should I run get_status before querying?** Yeah, always check `get_status`. It tells you if your API slots are low or if there's an active rate limit cooldown. Running large jobs when slots are tight wastes time. **Can I use the Overpass MCP Server for non-geospatial data?** No. This server is strictly for OpenStreetMap geometry and map features. If you need financial records or user profiles, you'll need a different database connector. **If my Overpass QL query fails using `execute_query`, how do I debug the syntax?** The server response will include a specific error code and message pointing to the failure location. You need to check your syntax carefully against standard Overpass QL documentation for common pitfalls like misplaced parentheses or incorrect relation types. **When should I use `execute_xapi` instead of running a query with `execute_query`?** Use `execute_xapi` only when you require the raw XML data output. For virtually all other tasks—especially those requiring easy parsing in an agent workflow—you should stick to `execute_query` because it guarantees JSON format. **Is there a limit to the size of the bounding box I can pass to `get_map`?** While the API handles large areas, extremely massive boxes often cause timeouts. You should break down your target region into smaller, manageable segments and run multiple calls to `get_map` sequentially for reliable results. **After checking my status with `get_status`, what should I do if the slot availability is zero?** If `get_status` reports no available slots, you must wait. Do not repeatedly send queries; monitor the API documentation for the specific cooldown period before attempting to run any tools again. **How do I find all restaurants in a specific city using this server?** You can ask the agent to use the `execute_query` tool with an Overpass QL string, for example: `[out:json];area[name='Berlin'];node(area)[amenity=restaurant];out;`. The agent will handle the execution and present the results. **Can I download raw map data for a specific coordinate range?** Yes. Use the `get_map` tool and provide the bounding box coordinates in the format `min_lon,min_lat,max_lon,max_lat`. This will return the raw OSM data for that area. **What should I do if the API returns a rate limit error?** Run the `get_status` tool. It will show you how many slots are available and if there is a cooldown period active for your IP address.