How to Set Up an MCP in ArcMap with OpenCode

With the Model Context Protocol (MCP) you can connect ArcMap 10.4–10.8 to an AI assistant, allowing you to run geoprocessing tools, manage layers, and automate workflows using natural language. In this tutorial we’ll use OpenCode, a free tool that requires no paid subscription.

Prerequisites

Make sure you have the following:

• ArcMap 10.4–10.8 installed on your computer.
• ArcGeek Tools Add-In: Download it from arcgeek.com/arcprotools (“Download Free” section, .esriAddIn 32-bit version). Run the file to install it.
• OpenCode: A free terminal tool with MCP support. Download it from opencode.ai.

Step 1: Install the UV Utility

We’ll install uv, the Python package manager that will run the MCP server. Open Windows PowerShell as Administrator, copy the line below, paste it, and run it by pressing Enter:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

This will install uv.exe in C:\Users\YOUR_USERNAME\.local\bin\. Write down your Windows username — you’ll need it later. Don’t close PowerShell yet.

Step 2: Start the MCP Server in ArcMap

Open ArcMap. If this is your first time using the add-in, the system will ask permission to copy files to C:\ProgramData\ArcGeekMTools. Click Yes to accept.

1. Enable the Add-In toolbar if it’s not visible: Customize → Toolbars → ArcGeek MCP.
2. Click Start MCP Server. A message will confirm that the server is listening on port 27173.

Note: ArcMap uses port 27173, while ArcGIS Pro uses 27172.

Step 3: Configure OpenCode

Edit the OpenCode global configuration file located at:

C:\Users\YOUR_USERNAME\.config\opencode\opencode.json

Add the ArcMap entry to the file. It should look like this:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "arcgis_arcmap": {
      "type": "local",
      "command": [
        "C:\\Users\\YOUR_USERNAME\\.local\\bin\\uv.exe",
        "--directory",
        "C:\\ProgramData\\ArcGeekMTools\\mcp_server",
        "run",
        "arcgis_mcp_server.py"
      ],
      "enabled": true
    }
  }
}

Warning: The folder for ArcMap is C:\ProgramData\ArcGeekMTools (with the M), not ArcGeekTools which is for ArcGIS Pro. Replace YOUR_USERNAME with your actual Windows username. Save the file and close OpenCode completely before continuing.

If you find this step difficult, you can ask OpenCode itself to help you configure the MCP. Just paste the code and tell it to set up the MCP within OpenCode; then grant it permission to make the changes.

Step 4: Restart and Verify

1. Close ArcMap and OpenCode.
2. It is recommended to restart your computer to avoid connection conflicts.
3. Open ArcMap and click Start MCP Server again.
4. Open OpenCode and type: ping mcp arcmap. If everything works, you’ll receive a response confirming that the ArcMap Add-In is connected and ready.

Available Tools

Once connected, the AI can run these operations directly in ArcMap:

• ping: Checks that the Add-In is responding.
• get_project_info: Retrieves information about the current document.
• get_layers: Lists the layers in the Table of Contents.
• add_vector_layer / add_raster_layer: Adds shapefiles, geodatabases, or rasters to the map.
• remove_layer: Removes a layer from the Table of Contents.
• zoom_to_layer: Zooms to the extent of a layer.
• execute_geoprocessing: Runs any ArcToolbox tool.
• apply_symbology: Applies symbology from a .lyr file.
• execute_code: Runs Python 2.7 (arcpy) code directly.

Compatibility with Other MCP Clients

Once the MCP server is installed and running in ArcMap, you’re not limited to OpenCode. You can connect from any application that supports the MCP protocol: Claude Desktop, Cursor, AntiGravity, or any other compatible client. You just need to add the corresponding configuration lines in each tool pointing to the same server folder (C:\ProgramData\ArcGeekMTools\mcp_server).

Important Notes

• Python 2.7: The execute_code tool runs scripts using ArcMap’s internal Python (2.7). It does not have access to arcpy.mapping.MapDocument("CURRENT"), so you must use explicit paths to MXD files.
• in_memory: In-memory data does not persist between separate execute_code calls. Use the scratch GDB or disk paths for intermediate data.
• For complex multi-step scripts, it’s better to use execute_code with the entire workflow in a single block rather than separate calls.
• You can even copy this entire guide and paste it into an AI assistant to help you configure your MCP.

Testing the Connection

With ArcMap and OpenCode open and the MCP server started, you can ask the AI things like:

• Hydrology: “Add the DEM, generate the stream network, and delineate the watershed from this point.”
• Contour lines: “Create contour lines every 20 meters from the DEM.”
• Morphometric analysis: “Calculate the area, perimeter, mean slope, and time of concentration for the watershed.”
• Geoprocessing: “Create a 500-meter buffer around this point and add it to the map.”
• Reports: “Export the results to a Word document and an Excel file with the statistics.”

From here on, the AI can run geoprocessing tools, write arcpy scripts, manage layers, and generate reports in your ArcMap project directly from the chat.