# jjsantos01/qgis_mcp architecture

> Architecture diagram of the GitHub repository jjsantos01/qgis_mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jjsantos01/qgis_mcp
- Repository: https://github.com/jjsantos01/qgis_mcp

## Overview

##### Project type and purpose
- This is a specialized full‑stack integration tool connecting the QGIS desktop application to an LLM (Claude AI) via the Model Context Protocol (MCP).
- Its goal is to allow Claude AI to manipulate QGIS projects (load/save projects, layers, run processing algorithms, execute arbitrary Python code) by sending commands to a QGIS plugin over a socket.

##### File structure
- Top level:
- main.py – entry‑point (could be a CLI wrapper or legacy)
- pyproject.toml, uv.lock – Python packaging and lock files
- assets/ – screenshots and UI assets for the README
- qgis_mcp_plugin/ – the QGIS plugin directory:
- __init__.py, metadata.txt – plugin manifest
- qgis_mcp_plugin.py – initializes a socket server inside QGIS and dispatches commands to the PyQGIS API
- src/qgis_mcp/ – the MCP server implementation:
- qgis_mcp_server.py – an MCP server (using uv) that speaks the MCP JSON‑RPC over stdio to Claude
- qgis_socket_client.py – a TCP socket client that connects to the QGIS plugin’s internal socket server to forward MCP commands
- main responsibilities:
- QGIS plugin → hosts a socket server inside QGIS
- MCP server → speaks MCP to Claude, forwards requests to plugin via socket client

##### Extract additional insights from the README
- Two main components are explicitly called out: “QGIS plugin” and “MCP Server.”
- Claude desktop is configured to launch the MCP server via `uv run qgis_mcp_server.py`.
- A suite of tools (ping, load_project, add_layer, execute_processing, execute_code, etc.) define the RPC surface exposed by the MCP server.

##### Key points to capture
– Two separate processes (MCP server vs. QGIS plugin) linked via a TCP socket
– The MCP protocol layer decoupled from the QGIS domain logic
– File system interactions as a core part of project and data manipulation
– Ability to expand with new MCP methods by adding handlers in the server and plugin

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External LLM
    ClaudeAI(Claude AI):::external

    %% Integration layer
    subgraph "Integration Layer"
        direction TB
        MCPServer["MCP Server"]:::server
        SocketClient["Socket Client"]:::server
    end

    %% QGIS side
    subgraph "QGIS Plugin Environment"
        direction TB
        QGISPlugin["QGIS Plugin"]:::plugin
        PyQGIS["PyQGIS API"]:::plugin
        QGISCore["QGIS Core"]:::plugin
    end

    %% Storage
    FileSystem[(File System)]:::storage

    %% Project Files
    subgraph "Project Files"
        direction TB
        Main["main.py"]:::files
        PyProject["pyproject.toml"]:::files
        UVLock["uv.lock"]:::files
        Assets["assets/"]:::files
    end

    %% Data flows
    ClaudeAI -->|"MCP JSON-RPC over stdio"| MCPServer
    MCPServer -->|"TCP socket commands"| SocketClient
    SocketClient -->|"TCP messages"| QGISPlugin
    QGISPlugin -->|"invokes"| PyQGIS
    PyQGIS -->|"executes operations"| QGISCore
    QGISPlugin -->|"read/write"| FileSystem

    %% Click events
    click MCPServer "https://github.com/jjsantos01/qgis_mcp/blob/main/src/qgis_mcp/qgis_mcp_server.py"
    click SocketClient "https://github.com/jjsantos01/qgis_mcp/blob/main/src/qgis_mcp/qgis_socket_client.py"
    click QGISPlugin "https://github.com/jjsantos01/qgis_mcp/blob/main/qgis_mcp_plugin/qgis_mcp_plugin.py"
    click __init__ "https://github.com/jjsantos01/qgis_mcp/blob/main/qgis_mcp_plugin/__init__.py"
    click metadata "https://github.com/jjsantos01/qgis_mcp/blob/main/qgis_mcp_plugin/metadata.txt"
    click Main "https://github.com/jjsantos01/qgis_mcp/blob/main/main.py"
    click PyProject "https://github.com/jjsantos01/qgis_mcp/blob/main/pyproject.toml"
    click UVLock "https://github.com/jjsantos01/qgis_mcp/blob/main/uv.lock"
    click Assets "https://github.com/jjsantos01/qgis_mcp/tree/main/assets/"

    %% Styles
    classDef external fill:#D0E6FF,stroke:#339,stroke-width:1px;
    classDef server fill:#DFF4DC,stroke:#397839,stroke-width:1px;
    classDef plugin fill:#FFE7C4,stroke:#C36E00,stroke-width:1px;
    classDef storage fill:#E0E0E0,stroke:#666,stroke-width:1px;
    classDef files fill:#F5F5F5,stroke:#AAA,stroke-width:1px;
```
