nkarasiak/qgis-mcp

Model Context Protocol (MCP)를 통해 QGIS를 Claude AI에 연결하여, Claude가 레이어 관리, 피처(feature) 편집, 프로세싱 알고리즘 실행, 지도 렌더링 등을 직접 제어할 수 있도록 합니다.

레이어 관리, 피처 편집, 프로세싱, 렌더링, 스타일링, 레이아웃 및 아틀라스(atlas) 작성, 교차 레이어 SQL, 플러그인 개발, 시스템 관리를 아우르는 102개의 MCP 도구를 제공합니다. QGIS 3.28–4.x 버전과 호환됩니다. Claude Code, Codex CLI, Gemini CLI, opencode, Claude Desktop, Cursor, VS Code, Windsurf, Zed 등에서 작동합니다.

Claude ←→ MCP Server (FastMCP) ←→ TCP socket ←→ QGIS Plugin (QTimer) ←→ PyQGIS API

QGIS Plugin(qgis_mcp_plugin/) — QGIS 내부에서 실행됩니다. QGIS의 이벤트 루프(event loop) 내에서 JSON 명령을 처리하는 논블로킹(Non-blocking) TCP 소켓 서버입니다.

MCP Server(src/qgis_mcp/server.py) — QGIS 외부에서 실행됩니다. FastMCP를 통해 QGIS 작업을 MCP 도구로 노출합니다.

클론(clone)이 필요하지 않습니다. QGIS 3.28 이상 및 uv가 필요합니다.

QGIS에서: Plugins

Manage and Install Plugins

QGIS MCP 검색 > Install.

QGIS를 재시작하고 QGIS MCP 도크 위젯(dock widget)에서 Start Server를 클릭하세요.

Claude Code

claude mcp add -s user qgis -- uvx --refresh-package qgis-mcp --from git+https://github.com/nkarasiak/qgis-mcp qgis-mcp-server

--refresh-package qgis-mcp 옵션은 실행할 때마다 uvx가 GitHub에서 최신 서버를 다시 가져오도록 하여 QGIS 플러그인과 동기화 상태를 유지합니다. 캐시된 버전에 고정하려면 이 옵션을 제외하세요 (더 빠른 시작, 수동 업데이트 필요).

범위(Scope) 참조:

플래그 (Flag)	저장 위치	가시성
`-s local` (기본값)	`.mcp.json` (gitignored)	사용자 본인, 해당 프로젝트
`-s project`	`.mcp.json` (committed)	팀 전체, 해당 프로젝트
`-s user`	`~/.claude.json`	사용자 본인, 모든 프로젝트

Codex CLI

codex mcp add qgis -- uvx --refresh-package qgis-mcp --from git+https://github.com/nkarasiak/qgis-mcp qgis-mcp-server

또는 ~/.codex/config.toml 파일을 직접 편집하세요:

[mcp_servers.qgis]
command = "uvx"
args = ["--refresh-package", "qgis-mcp", "--from", "git+https://github.com/nkarasiak/qgis-mcp", "qgis-mcp-server"]

Gemini CLI

~/.gemini/settings.json에 추가하세요:

{
"mcpServers": {
"qgis": {
...

opencode

프로젝트 루트의 opencode.json에 추가하세요:

{
"mcp": {
"qgis": {
...

Claude Desktop, Cursor, VS Code, Windsurf 및 기타

클라이언트의 MCP 설정 파일에 추가하세요:

{
"mcpServers": {
"qgis": {
...

플러그인 시작— QGIS에서 MCP 툴바 버튼을 클릭하거나 (또는 Plugins > QGIS MCP) 클릭한 후 "Start Server"를 클릭하세요. Claude와 대화하기— MCP 도구들이 자동으로 나타납니다. Claude에게 귀하의 QGIS 프로젝트를 작업하도록 요청하세요.

You have access to QGIS tools. Do the following:
1. Ping to check the connection
2. Create a new project and save it at "/tmp/my_project.qgz"
...

플러그인(QGIS 내부)과 MCP 서버(QGIS 외부)는 반드시 동기화 상태를 유지해야 합니다. 최신 서버가 이전 버전의 플러그인이 알지 못하는 명령을 보내면 오류가 반환됩니다. 업데이트 후에는 양쪽이 일치하는지 확인하기 위해 diagnose를 실행하세요.

구성 요소	원격 설치 (Remote install)	로컬 설치 (`git clone`)
QGIS 플러그인	`Plugins` > `Manage and Install Plugins` > Update	동일함 — 플러그인 매니저(Plugin Manager)가 QGIS Hub에서 새 버전을 가져옵니다
MCP 서버	설정에 `--refresh-package qgis-mcp`를 포함하면 (위 내용 참조), uvx가 클라이언트 재시작 시마다 최신 버전을 다시 가져옵니다. 이 옵션이 없으면 uvx가 캐시를 사용합니다 — `uvx --refresh-package qgis-mcp --from git+https://github.com/nkarasiak/qgis-mcp qgis-mcp-server` 명령으로 업데이트를 강제하세요	`git pull` 실행 후 MCP 서버 프로세스 재시작

uvx는 git 체크아웃(checkout)을 캐시하므로, 일반적인 설정으로는 자동 업데이트가 되지 않습니다. 위 설정에 포함된 --refresh-package qgis-mcp 플래그는 실행할 때마다 GitHub에서 이 패키지만 다시 해결(re-resolve)합니다 (mcp 의존성은 캐시된 상태로 유지됨). 트레이드오프(Tradeoff): 시작 시 약 1~3초 정도 느려지며 실행 시 네트워크가 필요합니다. 새로고침을 트리거하려면 MCP 클라이언트를 재시작하세요.

플러그인을 업데이트한 후에는, QGIS를 재시작하지 않고도 새로운 코드를 로드할 수 있도록 QGIS MCP 도크 위젯(dock widget)에서 Stop / Start를 클릭하거나 (Plugins > QGIS MCP > Reload Plugin)를 통해 다시 로드하세요.

카테고리	도구
프로젝트 (Project)	`load_project`, `create_new_project`, `save_project`, `get_project_info`
레이어 (Layers)	`get_layers`, `add_vector_layer`, `add_raster_layer`, `remove_layer`, `find_layer`, `create_memory_layer`, `set_layer_visibility`, `zoom_to_layer`, `get_layer_extent`, `set_layer_property`
피처 (Features)	`get_layer_features`, `add_features`, `update_features`, `delete_features`, `select_features`, `get_selection`, `clear_selection`, `get_field_statistics`
스타일링 (Styling)	`set_layer_style` (단일(single), 분류(categorized), 단계 구분(graduated))
렌더링 (Rendering)	`render_map`, `get_canvas_screenshot`, `get_canvas_extent`, `set_canvas_extent`
프로세싱 (Processing)	`execute_processing`, `list_processing_algorithms`, `get_algorithm_help`, `create_processing_model`
레이아웃 (Layouts)	`list_layouts`, `export_layout`, `create_layout`, `add_layout_map`, `add_layout_label`, `add_layout_legend`, `add_layout_scalebar`, `add_layout_picture`, `add_layout_table`, `get_layout_info`, `remove_layout`
아틀라스 (Atlas)	`configure_atlas`, `export_atlas`
쿼리 (Query)	`execute_sql`, `evaluate_expression`, `identify_features`
레이어 트리 (Layer tree)	`get_layer_tree`, `create_layer_group`, `move_layer_to_group`, `duplicate_layer`, `set_layer_order`
플러그인 (Plugins)	`list_plugins`, `get_plugin_info`, `reload_plugin`
시스템 (System)	`ping`, `diagnose`, `get_qgis_info`, `get_raster_info`, `get_message_log`, `execute_code`, `batch_commands`, `validate_expression`, `get_project_variables`, `set_project_variable`, `get_setting`, `set_setting`, `transform_coordinates`

모든 도구는 비동기(async) 방식으로 작동하며, 사람이 읽을 수 있는 제목과 주석(readOnly (읽기 전용), destructive (파괴적), idempotent (멱등성))을 포함합니다.

). 파괴적 (Destructive) 도구는 지원되는 경우 MCP elicitation (유도)을 통해 확인을 요청합니다. elicitation 기능이 없는 클라이언트는 도구가 이미 ToolAnnotations에 의해 제한되어 있으므로 정상적으로 진행합니다 (fail-open).

실행 시간이 긴 도구는 MCP logging (로깅)을 통해 진행 상황을 보고합니다.

QGIS_MCP_TOOL_MODE=compound를 설정하면 세분화된 도구들을 약 23개의 그룹화된 도구로 줄여, LLM 턴당 스키마 오버헤드 (schema overhead)를 절감할 수 있습니다. 각 복합 (compound) 도구는 action 파라미터를 가집니다:

QGIS_MCP_TOOL_MODE=compound uv run --no-sync src/qgis_mcp/server.py

그룹: system, project, layer, features, selection, style, canvas, render, processing, code, batch, layer_tree, plugins, variables, settings, expression, transform, message_log, layer_property.

환경 변수	기본값	설명
`QGIS_MCP_HOST`	`localhost`	소켓 연결을 위한 호스트
`QGIS_MCP_PORT`	`9876`	소켓 연결을 위한 포트
`QGIS_MCP_TRANSPORT`	`stdio`	MCP 전송 방식: `stdio` 또는 `streamable-http`
`QGIS_MCP_LOG_FILE`	`~/.local/share/qgis-mcp/server.log`	로그 파일 경로 (비워두면 비활성화)
`QGIS_MCP_LOG_LEVEL`	`INFO`	파일 로그 레벨
`QGIS_MCP_TOOL_MODE`	`granular`	`granular` (102개 도구) 또는 `compound` (~23개 그룹화된 도구)

git clone https://github.com/nkarasiak/qgis-mcp.git
cd qgis-mcp
python install.py # 플러그인 심볼릭 링크 생성 + MCP 클라이언트 설정

install.py 옵션: --clients claude-desktop,cursor, --remote (uv run 대신 uvx 사용), --profile myprofile, --uninstall.

Windows (Microsoft Store / MSIX Claude Desktop): install.py는 생성된 설정 파일에서 cwd 대신 --directory를 사용합니다. 이는 MSIX 샌드박스 내에서 MCP 서버를 실행하여 cwd를 조용히 누락시키는 Store 설치형 Claude Desktop에 필수적입니다. 수동으로 설정하는 경우, uv --directory "/path/to/qgis-mcp" run --no-sync src/qgis_mcp/server.py를 사용하십시오.

— 이는 MSIX 및 독립 실행형 (standalone) 설치 모두에서 작동합니다. 설정 파일이 %APPDATA%\Claude\ 대신 %LOCALAPPDATA%\Packages\Claude_<id>\LocalCache\Roaming\Claude\ 아래에 있다면 Store 설치 버전임을 식별할 수 있습니다.

# 단위 테스트 (QGIS 불필요 — 모킹된 소켓 사용)
uv run --no-sync pytest tests/test_mcp_tools.py -v
# 통합 테스트 (QGIS 플러그인 실행 필요)
...

이 프로젝트는 GNU GPL v2 또는 그 이후 버전의 라이선스를 따릅니다.