QGISMCP for Windsurf: Setup & Config

What you can do with QGISMCP in Windsurf

A live QGIS bridge spanning layer operations, processing algorithms, custom code, and map output.

• Load vector and raster layers and inspect their contents.
• Render map images after assisted styling or analysis.

Before you start: QGISMCP in Windsurf

• QGIS 3.x; README testing was limited to 3.22
• Python 3.10 or later
• uv
• Claude Desktop
• The enabled QGIS MCP plugin and its running socket server

Replace the documented absolute-path placeholder with the checkout location. Copy qgis_mcp_plugin into the active profile's plugins directory, restart QGIS, enable it, then use its Start Server action. No required environment variables are stated.

QGISMCP Windsurf configuration

1. Choose Windsurf configuration scope

   For QGISMCP, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

2. Add QGISMCP to Windsurf

   Use the qgis_mcp entry below in mcpServers. Keep QGISMCP's documented stdio connection fields and your other Windsurf entries.

3. Check QGISMCP in Windsurf

   QGISMCP: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

{
  "mcpServers": {
    "qgis_mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/PARENT/REPO/FOLDER/qgis_mcp/src/qgis_mcp",
        "run",
        "qgis_mcp_server.py"
      ],
      "env": {}
    }
  }
}

QGISMCP tools available to Windsurf

QGISMCP's stored tool list documents 15 tools; compare it with Windsurf's connected tool list, because the stored list is not a live check.

ping

After refreshing QGISMCP in Windsurf settings, check Cascade's tool list for ping.

Check connectivity with the QGIS plugin server.

get_qgis_info

After refreshing QGISMCP in Windsurf settings, check Cascade's tool list for get_qgis_info.

Inspect details of the running QGIS installation.

load_project

After refreshing QGISMCP in Windsurf settings, check Cascade's tool list for load_project.

create_new_project

After refreshing QGISMCP in Windsurf settings, check Cascade's tool list for create_new_project.

get_project_info

After refreshing QGISMCP in Windsurf settings, check Cascade's tool list for get_project_info.

add_vector_layer

After refreshing QGISMCP in Windsurf settings, check Cascade's tool list for add_vector_layer.

Load vector data as a project layer.

add_raster_layer

After refreshing QGISMCP in Windsurf settings, check Cascade's tool list for add_raster_layer.

Load raster data as a project layer.

get_layers

After refreshing QGISMCP in Windsurf settings, check Cascade's tool list for get_layers.

Enumerate layers in the active project.

remove_layer

After refreshing QGISMCP in Windsurf settings, check Cascade's tool list for remove_layer.

zoom_to_layer

After refreshing QGISMCP in Windsurf settings, check Cascade's tool list for zoom_to_layer.

get_layer_features

After refreshing QGISMCP in Windsurf settings, check Cascade's tool list for get_layer_features.

execute_processing

After refreshing QGISMCP in Windsurf settings, check Cascade's tool list for execute_processing.

save_project

After refreshing QGISMCP in Windsurf settings, check Cascade's tool list for save_project.

Save the active project at a requested path.

render_map

After refreshing QGISMCP in Windsurf settings, check Cascade's tool list for render_map.

Export the current map view as an image file.

execute_code

After refreshing QGISMCP in Windsurf settings, check Cascade's tool list for execute_code.

Run arbitrary PyQGIS source supplied as a string.

QGISMCP: full stored tool descriptions

Troubleshooting QGISMCP in Windsurf

• Check uv on the machine running Windsurf's MCP integration for QGISMCP; refresh MCP and inspect Cascade's tools.
• QGISMCP uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Requires manual plugin installation and starting its server in QGIS.
• Known limitation: The README reports testing only on QGIS 3.22.
• Known limitation: Arbitrary Python execution carries an explicit caution in the README.
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions