# QGIS MCP — GIS GEORGIA

**KA** · [English below](#english)

## ქართულად

Claude Code (ან სხვა MCP კლიენტი) მართავს QGIS-ს ავტომატურად. პროექტი ორი ნაწილისგან შედგება:

1. **QGIS ფლაგინი** (`plugin/qgis_mcp_ge`) — პატარა GUI პანელი ღილაკებით. QGIS-ის შიგნით უშვებს ლოკალურ სერვისს, რომელიც ასრულებს ბრძანებებს ღია სესიაში.
2. **MCP სერვერი** (`src/qgis_mcp_ge_server`) — Claude Code-ს აკავშირებს ფლაგინთან (GUI რეჟიმი) ან მუშაობს **headless** რეჟიმში (GUI-ს გარეშე, ცალკე QGIS Python პროცესით).

```
Claude Code ──stdio──> MCP სერვერი ──TCP 127.0.0.1 + ტოკენი──> QGIS ფლაგინი (GUI)
                           └────────── subprocess ──────────> QGIS Python (headless)
```

### ინსტრუმენტები (ეტაპი 1)

| ინსტრუმენტი | რას აკეთებს |
|---|---|
| `qgis_status` | კავშირის შემოწმება, QGIS-ის ვერსია |
| `run_pyqgis` | PyQGIS კოდის შესრულება (`iface`, `project`; შედეგი → `result`) |
| `list_layers` / `layer_info` | ფენების სია / ფენის დეტალები (ველები, ობიექტების რაოდენობა) |
| `add_layer` / `remove_layer` | ფენის დამატება / წაშლა |
| `export_map` | რუკის ექსპორტი სურათად |
| `project_info` / `save_project` / `load_project` | პროექტის ინფო, შენახვა, ჩატვირთვა |
| `headless_command` | იგივე ბრძანებები GUI-ს გარეშე (`project=...`, `save=true`) |
| `headless_algorithm` / `headless_list_algorithms` | Processing ალგორითმები (`native:buffer` და ა.შ.) |

### უსაფრთხოება

- სერვისი უსმენს **მხოლოდ `127.0.0.1`-ს**; გარედან მიუწვდომელია.
- ყოველი მოთხოვნა საჭიროებს **ტოკენს** (პანელში გენერირდება, შედარება მუდმივ დროში). ტოკენი იწერება `~/.qgis-mcp-ge/session.json`-ში, რომ MCP სერვერმა თავად იპოვოს.
- `run_pyqgis` თვითნებური კოდის შესრულებაა — პანელში გამოსართავი ჩექბოქსია. გამოიყენე მხოლოდ სანდო კლიენტთან.

### ინსტალაცია

1. დააკოპირე `plugin/qgis_mcp_ge` QGIS-ის ფლაგინების საქაღალდეში (ან გაუშვი `python scripts/install_plugin.py`) და ჩართე **Plugins → Manage** ში. QGIS 3.28+ და QGIS 4 მხარდაჭერილია.
2. QGIS-ში გახსენი პანელი **QGIS MCP**, ენა აირჩიე (ქართული/English), დააჭირე **გაშვება**.
3. დააჭირე **Claude Code ბრძანების კოპირება** და გაუშვი ტერმინალში, ან ხელით:

```bash
claude mcp add qgis -- uvx --from git+https://github.com/GIS-GEORGIA/qgis-mcp qgis-mcp-ge
```

4. Headless რეჟიმისთვის ფლაგინი არ არის საჭირო; თუ QGIS ავტომატურად ვერ მოიძებნა, დააყენე `QGIS_PYTHON` (მაგ. `C:\Program Files\QGIS 3.44.5\bin\python-qgis.bat`) და `QGIS_PROCESS`.

### განვითარება და ტესტები

```bash
# Windows (PowerShell)
& "C:\Program Files\QGIS 3.44.5\bin\python-qgis.bat" tests\smoke_bridge.py
```

---

## English

Let Claude Code (or any MCP client) drive QGIS. Two parts:

1. **QGIS plugin** (`plugin/qgis_mcp_ge`) — a small button-driven dock panel that runs a local service inside QGIS and executes commands in the open session.
2. **MCP server** (`src/qgis_mcp_ge_server`) — connects Claude Code to the plugin (GUI mode), or runs **headless** (no GUI, separate QGIS Python process).

### Tools (stage 1)

`qgis_status`, `run_pyqgis`, `list_layers`, `layer_info`, `add_layer`, `remove_layer`, `export_map`, `project_info`, `save_project`, `load_project`, plus headless: `headless_command`, `headless_algorithm`, `headless_list_algorithms`.

### Security

- Listens on **`127.0.0.1` only**.
- Every request needs a **token** (generated in the panel, constant-time comparison); it is written to `~/.qgis-mcp-ge/session.json` so the MCP server can find it.
- `run_pyqgis` executes arbitrary code by design; it can be disabled with a checkbox in the panel. Only use it with clients you trust.

### Install

1. Copy `plugin/qgis_mcp_ge` into your QGIS plugins folder (or run `python scripts/install_plugin.py`) and enable it. QGIS 3.28+ and QGIS 4 supported.
2. Open the **QGIS MCP** panel, pick your language, press **Start**.
3. Register the MCP server:

```bash
claude mcp add qgis -- uvx --from git+https://github.com/GIS-GEORGIA/qgis-mcp qgis-mcp-ge
```

4. Headless mode does not need the plugin; set `QGIS_PYTHON` / `QGIS_PROCESS` if auto-detection fails.

### Roadmap

Async long-running jobs, layer styling helpers, print layouts, recipes — inspired by ideas in [QgisRemoteMCP](https://github.com/nic01asFr/QgisRemoteMCP), [jjsantos01/qgis_mcp](https://github.com/jjsantos01/qgis_mcp) and [nkarasiak/qgis-mcp](https://github.com/nkarasiak/qgis-mcp). This codebase is written from scratch.

## License

MIT — see [LICENSE](LICENSE).