QGIS MCP – AI 기반 QGIS 제어

무엇인가요 – Model Context Protocol (MCP)를 지원하는 모든 AI 모델이 QGIS와 직접 통신할 수 있도록 해주는 두 부분으로 구성된 오픈소스 도구입니다. 가벼운 TCP 서버(MCP 서버)는 QGIS 외부에서 실행되며, 118개의 JSON 기반 명령어(레이어 관리, 편집, 처리, 렌더링 등)를 노출합니다. QGIS 내부에는 비차단 플러그인이 있으며, 이는 MCP JSON 명령어를 수신하고 PyQGIS API를 호출합니다. 따라서 LLM은 일반적인 코딩 어시스턴트 클라이언트(Claude Code, Codex CLI, Gemini 등)를 통해 프로젝트 생성, 피처 편집, 처리 알고리즘 실행, 지도 렌더링 등을 모두 AI 기반 명령어로 수행할 수 있습니다.

핵심 구성 요소

구성 요소	역할
QGIS 플러그인 (`qgis_mcp_plugin/`)	QGIS 내부에서 실행되며, MCP JSON 명령어를 수신하고 PyQGIS 호출로 매핑하는 TCP 소켓을 호스팅합니다.
MCP 서버 (`src/qgis_mcp/server.py`)	별도 프로세스로 실행됩니다(‘uvx’로 시작). 118개의 MCP 도구를 구현하고 소켓을 통해 플러그인으로 전달합니다.

아키텍처는 다음과 같습니다:

AI 에이전트 ⇄ MCP 서버 (FastMCP) ⇄ TCP 소켓 ⇄ QGIS 플러그인 ⇄ PyQGIS API

주요 기능 (선택 사항)

프로젝트 – 생성, 로드, 저장, CRS 조회.
레이어 – 벡터, 래스터, 웹 레이어 추가/제거; 가시성 설정; 경계 조회.
피처 – 목록, 추가, 지오메트리 업데이트, 삭제, 선택, 통계 계산.
스타일링 – QML 적용, 분류/그레이딩 스타일 설정, 레이블 설정.
처리 – QGIS 처리 알고리즘 실행, 배치 실행, 모델 처리.
렌더링 – 지도 이미지, 3D 스크린샷, 캔버스 스크린샷 생성.
레이아웃 및 아틀라스 – 레이아웃 생성, 지도/범례/스케일바 추가, PDF 내보내기, 아틀라스 실행.
시스템 – ping, 진단, 임의의 Python 코드 실행, 배치 명령.

모든 도구는 비동기이며, 인간이 읽기 쉬운 제목을 가지며, readOnly, destructive, idempotent 등의 주석을 포함합니다. 파괴적 작업은 클라이언트의 확인 UI를 존중하며, QGIS_MCP_AUTO_CONFIRM=0으로 설정하면 서버가 다시 확인을 요청하도록 강제할 수 있습니다.

설치 및 설정

QGIS 플러그인 – QGIS에서 플러그인 → 플러그인 관리 및 설치로 이동하여 QGIS MCP를 검색하고 설치한 후 재시작합니다. 새로운 도크 위젯에서 **[서버 시작]**을 클릭하세요.
MCP 서버 – Python 패키지 매니저 uv가 필요합니다. 어떤 터미널에서든 다음 중 하나를 실행하세요. 예: Claude Code용:
```
claude mcp add -s user qgis \
    -- uvx --from https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip qgis-mcp-server
```
(Codex, Gemini, Kimi, Copilot CLI, LM Studio, Opencode, Hermes 등용 유사한 uvx 명령어도 제공됩니다.)
클라이언트에서 MCP 호출을 하면 서버가 자동으로 시작됩니다. 아카이브를 다운로드하고 캐시한 후 qgis-mcp-server를 실행합니다.

옵션 설정 – 환경 변수로 호스트/포트 변경, 공유 토큰(QGIS_MCP_TOKEN) 활성화, 여러 QGIS 인스턴스 실행, 세부(118) 또는 복합(27) 도구 세트 선택, 로깅 제어가 가능합니다.

빠른 사용 예제

QGIS 도구에 접근할 수 있습니다. 다음 작업을 수행하세요:
1. ping
2. create_new_project path="/tmp/my_project.qgz"
3. add_vector_layer path="resources/data/world_map.gpkg"
4. filter features where adm0_a3 = "USA"
5. render_map width=800 height=600
6. save_project

LLM 클라이언트에 전송하면 모델은 해당 MCP 도구를 호출하고, QGIS 창에는 미국의 렌더링된 지도가 표시됩니다.

업데이트 방법

플러그인 – QGIS 플러그인 매니저를 통해 업데이트(또는 매니저를 통해 ZIP 재설치).

서버 – 캐시된 패키지를 새로 고치려면:

uvx --refresh-package qgis-mcp \
    --from https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip qgis-mcp-server

이후 클라이언트를 재시작하세요.

기여 및 테스트

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

유닛 테스트(정상 QGIS 필요 없음)는 uv run pytest tests/test_mcp_tools.py로 실행합니다. 실행 중인 QGIS 인스턴스가 필요한 통합 테스트는 uv run pytest tests/test_qgis_live.py로 실행합니다.

라이선스

QGIS 플러그인 – GNU GPL v2 이상.
MCP 서버 – MIT.

결론 – QGIS MCP는 MCP 호환 LLM을 완전 기능의 GIS 어시스턴트로 전환하여, 개발자와 분석가가 자연어 프롬프트나 코드 완성 도구를 통해 QGIS를 완전히 스크립트화할 수 있도록 합니다.

nkarasiak/qgis-mcp

QGIS MCP – AI 기반 QGIS 제어