QGISMCP

Before Claude can use the tools, the socket server must be running inside QGIS.

1. Open QGIS.
2. Navigate to the plugins menu.
3. Select QGIS MCP > QGIS MCP.
4. Click the Start Server button.

QGISMCP requires QGIS 3.X (tested on 3.22), Claude Desktop, Python 3.10+, and the uv package manager.

Follow these steps to set up the environment:

1. Install uv (Required before proceeding):

   • macOS: brew install uv
   • Windows (PowerShell): powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
   • Other: Follow instructions at https://docs.astral.sh/uv/getting-started/installation/

2. Clone the repository:

   git clone git@github.com:jjsantos01/qgis_mcp.git

To enable the socket server within QGIS, you must manually install the plugin folder into your QGIS profile directory.

1. Locate your QGIS profile folder:

   • In QGIS, go to Settings -> User profiles -> Open active profile folder.
   • Navigate to the Python/plugins subfolder.
   • Windows default: C:\Users\USER\AppData\Roaming\QGIS\QGIS3\profiles\default\python\plugins
   • macOS default: ~/Library/Application\ Support/QGIS/QGIS3/profiles/default/python/plugins

2. Copy the qgis_mcp_plugin folder from the cloned repository into that plugins folder.

3. Restart QGIS.

4. Enable the plugin:

   • Go to Plugins > Installing and Managing Plugins.
   • Select the All tab.
   • Search for "QGIS MCP".
   • Check the box to enable it.

To allow Claude to communicate with the QGIS MCP server, you must add the server configuration to your claude_desktop_config.json file.

1. Open Claude Desktop.
2. Navigate to Claude > Settings > Developer > Edit Config.
3. Add the qgis server entry under mcpServers.

Note: You must replace /ABSOLUTE/PATH/TO/PARENT/REPO/FOLDER/ with the actual absolute path to the repository on your machine.

{
    "mcpServers": {
        "qgis": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/PARENT/REPO/FOLDER/qgis_mcp/src/qgis_mcp",
                "run",
                "qgis_mcp_server.py"
            ]
        }
    }
}

The execute_code tool allows you to run any valid PyQGIS code directly within the QGIS instance. This is useful for complex tasks that are not covered by the standard toolset.

Note: Ensure the QGIS plugin is running and the MCP server is connected before attempting to execute code.

# Example: Accessing the active layer via execute_code
execute_code(code=""" 
layer = QgsProject.instance().mapLayersByName('my_layer')[0] 
print(layer.name()) 
""")

Use the following methods to manipulate layers within the active QGIS project:

• add_vector_layer(path, name=None, provider="ogr"): Adds a vector layer.
• add_raster_layer(path, name=None, provider="gdal"): Adds a raster layer.
• get_layers(): Returns a list of all layers in the project.
• remove_layer(layer_id): Removes a specific layer using its ID.
• zoom_to_layer(layer_id): Zooms the map view to the extent of the specified layer.
• get_layer_features(layer_id, limit=10): Retrieves features from a vector layer up to a specified limit.

The QgisMCPClient class provides a programmatic interface to interact with a running QGIS instance via a socket connection. By default, it connects to localhost on port 9876.

To use the client, you must first instantiate it, call .connect(), and then use the provided high-level methods to execute commands. The client handles JSON serialization and ensures complete message reception by continuously reading from the socket until a valid JSON object is decoded.

from qgis_mcp.qgis_socket_client import QgisMCPClient

client = QgisMCPClient(host='localhost', port=9876)
if client.connect():
    # Perform operations
    info = client.get_qgis_info()
    print(info)
    client.disconnect()

Use these methods to handle project files and visual output:

• load_project(path): Loads a QGIS project file from the specified path.
• save_project(path=None): Saves the current project. If path is provided, it saves to that location; otherwise, it uses the current project path.
• render_map(path, width=800, height=600): Renders the current map view to an image file at the specified path with the given dimensions.

Use the add_vector_layer tool to bring vector data into your current QGIS project. You can specify the file path, the data provider (defaulting to ogr), and an optional name for the layer.

Parameters:

• path (str): The filesystem path to the vector file.
• provider (str): The provider to use (e.g., ogr). Defaults to ogr.
• name (str, optional): The name to assign to the layer in the QGIS layers panel.

# Example: Adding a shapefile
add_vector_layer(path="/data/roads.shp", provider="ogr", name="Main Roads")

The main.py file serves as the CLI entrypoint for the qgis-mcp server. When executed, it initializes the Model Context Protocol (MCP) server environment. Currently, the entrypoint provides a basic greeting to verify the execution environment.

python main.py