# CARTO MCP for AI Agents MCP > CARTO lets your AI agents run spatial SQL directly against cloud data warehouses (BigQuery, Snowflake). It handles everything from geocoding thousands of addresses to calculating complex service areas and optimal driving routes. ## Overview - **Category:** databases - **Price:** Free - **Tags:** spatial-analytics, gis, spatial-sql, location-intelligence, data-warehousing, geospatial-data ## Description This MCP gives your agent direct access to CARTO's full suite of cloud-native spatial analytics. You don’t need to touch the GIS interface or write complex API calls for every task. Instead, you simply ask your AI client to perform actions like 'Find all stores within a 15-minute drive of downtown.' It translates that request into the necessary geospatial commands: running quick SQL queries on your warehouse data, batch processing hundreds of addresses, or generating accurate travel isoline boundaries. The power comes from being able to orchestrate these complex steps conversationally. Whether you're importing a massive CSV file with coordinates or comparing two datasets using spatial joins, your agent handles the heavy lifting. Since it connects via Vinkius, you access all of this capability—from data ingestion to final map generation—through one single connection point. ## Tools ### calculate_isoline Generates a polygon showing the reachable area from a point based on travel time or distance thresholds. ### calculate_route Finds the best driving path between two coordinates and returns the total distance in meters and estimated duration in seconds. ### create_async_sql_job Submits a large, complex SQL query as an asynchronous job that runs in your data warehouse for heavy computations that take minutes to complete. ### execute_sql_query Runs immediate analytical queries against your connected data warehouse using standard spatial functions. ### geocode_address Converts a single text address string into precise latitude and longitude coordinates. ### geocode_batch_addresses Processes multiple addresses at once, converting entire lists of street names into geo-coded coordinates efficiently. ### get_import_status Checks if a previously started data import job is finished and reports the status or any errors that occurred. ### import_external_file Loads an external file, like GeoJSON or CSV, into your data warehouse by pointing to its public URL. ### list_map_datasets Retrieves a list of all existing map datasets and tables within your CARTO organization for review. ### poll_async_job_status Periodically checks the status of an asynchronous SQL job, confirming if it's pending, running, or completed. ## Prompt Examples **Prompt:** ``` I'm opening a new branch. Can you calculate the 15-minute drive area around this proposed location and cross-reference it with available demographic data? ``` **Response:** ``` **Isoline Analysis Complete** Based on current traffic models, the optimal service zone is generated as follows: * **Coverage Area:** Approximately 3.2 square miles. * **Key Populations Included:** >15,000 residents within a 10-minute radius. * **High Traffic Corridors:** The main routes are covered by the path geometry below. [GeoJSON Polygon Data Here] This boundary shows your potential reach and confirms high population density in the southwest quadrant. ``` **Prompt:** ``` We got a list of 500 store locations. Can you validate all those addresses using real-world coordinates? ``` **Response:** ``` **Batch Geocoding Results** Successfully processed 500 entries. Here’s a sample: | Address | Lat | Lon | Status | | :--- | :-: | :-: | :--- | | 123 Main St, City A | 40.71 | -74.01 | OK | | 789 Oak Ave, City B | 34.05 | -118.25 | OK | | PO Box 100, Unknown | N/A | N/A | INVALID | *Note: The batch process flagged 5 addresses as invalid for manual review.* ``` **Prompt:** ``` We need to run an advanced query that joins our sales data with the census boundary polygons. Can you set it up? ``` **Response:** ``` **Async SQL Job Initiated** I've submitted your complex spatial join request. The job ID is `job_xyz123`. * **Status:** Pending (Running) * **Estimated Time:** 8-10 minutes. You can check the status anytime using this ID. I will notify you when the results table (`sales_with_census`) is available. ``` ## Capabilities ### Run Spatial SQL Queries Execute quick analytical queries or long-running batch transformations directly against your BigQuery, Snowflake, or Redshift data warehouse. ### Batch Geocode Addresses Convert large lists of unstructured street addresses into precise latitude and longitude coordinates efficiently in a single request. ### Calculate Service Areas (Isolines) Generate polygons showing the area reachable by car or foot within a specified travel time or distance from any given point. ### Find Optimal Driving Routes Determine the shortest, most efficient driving path between two points, including total distance and estimated duration. ### Import External Data Files Upload massive external datasets—like CSV or GeoJSON files—from a public URL and load them into your connected data warehouse for analysis. ## Use Cases ### Planning New Store Locations A retail strategist needs to test five potential store sites. They ask their agent to use `calculate_isoline` for a 10-minute drive time around each site, letting them visualize the full catchment area and select the most viable spot. ### Auditing Customer Data Quality A data scientist receives a spreadsheet of 5,000 addresses. They use `geocode_batch_addresses` to validate every single entry against real-world coordinates before running any expensive analytics queries. ### Running Large-Scale Data Migrations A data engineer needs to run a complex spatial join across two massive tables. Instead of timing out, they use `create_async_sql_job` and then monitor progress with the related polling tools. ### Calculating Supply Chain Efficiency The operations team asks their agent to calculate the fastest driving path between a regional distribution center and three client sites using `calculate_route`, optimizing fuel consumption for the fleet. ## Benefits - The `geocode_batch_addresses` tool lets you process thousands of customer addresses in one go, saving hours of manual data cleanup. - You can run complex queries using `execute_sql_query` to quickly join spatial datasets with standard business metrics without leaving the chat window. - Calculating service boundaries is simple: use `calculate_isoline` to instantly graph all areas within a 15-minute drive of a store site for planning. - Handling large data transfers? Just point your agent at an external file URL, and `import_external_file` loads it directly into your warehouse. - The asynchronous job tools (`create_async_sql_job`, `poll_async_job_status`) handle massive ETL tasks that would time out if run in a simple query. ## How It Works The bottom line is: you talk to your AI client like a colleague, and it handles all the complex geospatial data plumbing. 1. First, subscribe to the CARTO MCP on Vinkius and provide your active CARTO Organization credentials and API Key. 2. Next, give your AI client permission to run spatial commands against your data warehouse—whether that's running a simple query or submitting an async job. 3. Finally, ask your agent for the analysis you need. It executes the required steps (like geocoding addresses or calculating routes) and hands you the structured, usable result. ## Frequently Asked Questions **How does CARTO MCP help me find optimal routes between sites?** It calculates the most efficient driving path, giving you not just a line on a map, but precise total distance in meters and estimated time in seconds. This is useful for optimizing your delivery fleet. **Is CARTO MCP good for handling huge lists of addresses?** Yes. You don't have to geocode them one by one. The batch processing tools allow you to send entire spreadsheets of addresses and get back validated coordinates for every single entry. **What if my data is in a different cloud warehouse, not BigQuery?** The CARTO MCP supports querying your data directly from Snowflake, Redshift, or PostgreSQL. It works with the spatial features built into those databases. **Can I use this tool for planning new store coverage areas?** Absolutely. You can calculate service isolines—the actual physical area you'll reach within a set driving time—allowing you to select sites that cover the right population density. **Is CARTO MCP better than writing custom API scripts?** Yes, it’s much easier. Instead of managing multiple API calls for geocoding, routing, and SQL jobs, you just ask your agent to perform the entire multi-step process conversationally. **Does CARTO MCP handle data I need to load from an external file?** It does. You can provide a publicly accessible URL for any standard format—CSV, GeoJSON, or Shapefile—and the tool will automatically ingest and prepare it in your warehouse.