OpenAI Codex QGIS MCP

OpenAI Codex QGIS MCP connects Codex Desktop to QGIS Desktop through the Model Context Protocol (MCP). It bundles both sides needed for Codex:

• A Codex-compatible MCP server.

• A QGIS Desktop plugin that opens a local socket server.

• A Codex plugin manifest, MCP config, and GIS pre-flight skill.

This project is intentionally separated from the Claude-compatible QGIS MCP implementation. The Codex bundle uses port 9877 by default so it can coexist with the original Claude-oriented QGIS MCP plugin on port 9876.

Features

• Connect OpenAI Codex Desktop to QGIS Desktop.

• Create, load, inspect, and save QGIS projects.

• Add and remove vector or raster layers.

• List layers and inspect vector features.

• Zoom to layers and render the current map view to an image.

• Run QGIS Processing algorithms.

• Execute focused PyQGIS code inside QGIS Desktop when needed.

• Provide a Codex GIS skill for CRS, geometry, schema, extent, and null-geometry pre-flight checks.

Repository Layout

• src/qgis_mcp_codex/ - bundled Codex-compatible MCP server and socket client.

• qgis_mcp_codex_plugin/ - QGIS Desktop plugin for Codex, listening on localhost:9877.

• plugins/qgis-mcp-codex/ - Codex plugin manifest, MCP config, launcher, and skill.

• .agents/plugins/marketplace.json - local Codex plugin marketplace entry.

• scripts/package_qgis_plugin.ps1 - helper to package the QGIS plugin as a ZIP.

Requirements

• QGIS 3.x.

• OpenAI Codex Desktop.

• Python 3.12 or newer for the MCP server.

• uv package manager.

• Windows PowerShell for the included packaging helper.

Install uv on Windows PowerShell:

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

QGIS Desktop Plugin Setup

Manual install:

1. Copy the folder qgis_mcp_codex_plugin to your QGIS profile plugin directory.

2. The final path usually looks like:

   C:\Users\User\AppData\Roaming\QGIS\QGIS3\profiles\default\python\plugins\qgis_mcp_codex_plugin

3. Confirm these files are directly inside that folder:

   metadata.txt
   __init__.py
   qgis_mcp_codex_plugin.py

4. Restart QGIS Desktop.

5. Open Plugins > Manage and Install Plugins.

6. Enable QGIS MCP Codex.

7. Open Plugins > QGIS MCP Codex > QGIS MCP Codex.

8. Click Start Server.

ZIP install:

1. Open PowerShell in the repository root, the folder that contains this README.md.

2. Run:

.\scripts\package_qgis_plugin.ps1

3. This creates:

dist\qgis_mcp_codex_plugin.zip

4. In QGIS, open Plugins > Manage and Install Plugins > Install from ZIP.

5. Select the generated ZIP file:

   <repo-root>\dist\qgis_mcp_codex_plugin.zip

6. Click Install Plugin, restart QGIS if needed, then enable QGIS MCP Codex.

Codex Desktop Setup

Edit your Codex Desktop config file. On Windows, the usual path is:

C:\Users\<your-user>\.codex\config.toml

For example, on a machine where the Windows user is User, the path is:

C:\Users\User\.codex\config.toml

If your Codex config lives somewhere else, edit that config.toml instead.

Add this local plugin marketplace configuration:

[marketplaces.qgis-mcp-local]
source_type = "local"
source = 'C:\path\to\OpenAICodex-QGIS-MCP'

[plugins."qgis-mcp-codex@qgis-mcp-local"]
enabled = true

Replace C:\path\to\OpenAICodex-QGIS-MCP with the absolute path to this repository.

Restart Codex Desktop after editing the config.

The Codex MCP server entry is named qgis. It launches:

plugins/qgis-mcp-codex/scripts/launch_qgis_mcp.py

The launcher runs the bundled server:

src/qgis_mcp_codex/qgis_mcp_server.py

Test The Connection

1. Start QGIS Desktop.

2. Start the QGIS MCP Codex plugin server on port 9877.

3. Restart Codex Desktop if you just changed plugin config.

4. Ask Codex:

   Use the QGIS MCP tool to ping QGIS.

Expected response includes pong: true.

You can also ask:

Use the QGIS MCP tool to get QGIS info and current project info.

Available MCP Tools

• ping

• get_qgis_info

• load_project

• create_new_project

• get_project_info

• add_vector_layer

• add_raster_layer

• get_layers

• remove_layer

• zoom_to_layer

• get_layer_features

• execute_processing

• save_project

• render_map

• execute_code

execute_code runs arbitrary PyQGIS code inside QGIS Desktop. Use it carefully and prefer narrower tools or QGIS Processing algorithms when possible.

Troubleshooting

• If Codex cannot connect, confirm QGIS Desktop is open and QGIS MCP Codex is running on port 9877.

• If QGIS does not detect the plugin, confirm the folder is under python\plugins and is not nested twice.

• If port 9877 is busy, change the port in the QGIS plugin UI and update the bundled MCP server default in src/qgis_mcp_codex/qgis_mcp_server.py.

• If uv is not found, install it and restart Codex Desktop.

• If Codex does not show the plugin after config changes, restart Codex Desktop.

Credits

This project is based on and adapted from jjsantos01/qgis_mcp, which connects QGIS Desktop to Claude Desktop through MCP.

The original QGIS MCP project is itself based on the BlenderMCP approach by Siddharth Ahuja. This repository separates the Codex-compatible implementation into its own MCP server, QGIS plugin, Codex plugin metadata, and default port.