# 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
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:

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

3. Confirm these files are directly inside that folder:

   ```text
   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:

```powershell
.\scripts\package_qgis_plugin.ps1
```

3. This creates:

```text
dist\qgis_mcp_codex_plugin.zip
```

4. In QGIS, open `Plugins > Manage and Install Plugins > Install from ZIP`.
5. Select the generated ZIP file:

   ```text
   <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:

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

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

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

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

Add this local plugin marketplace configuration:

```toml
[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:

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

The launcher runs the bundled server:

```text
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:

   ```text
   Use the QGIS MCP tool to ping QGIS.
   ```

Expected response includes `pong: true`.

You can also ask:

```text
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](https://github.com/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.