QGIS MCP Agent Framework

🚀 Build your own LLM-powered QGIS agent with 333 geospatial processing tools across 14 specialized MCP services.

A complete framework for creating intelligent agents that understand natural language and automatically execute QGIS operations.

✨ Features

🤖 Ready-to-Use Agent - LLM-powered agent with intelligent tool selection
🎯 333 QGIS Tools - Complete QGIS processing toolkit via MCP
🔧 14 Specialized Services - Vector, raster, GDAL, cartography, and more
🌐 Multi-Service Support - Connect multiple services simultaneously
📦 Modular Architecture - Use only the tools you need
🛠️ Easy Integration - Simple Python API for custom agents

🏗️ Architecture

┌─────────────────────────────────────────────────┐
│                Your LLM Agent                   │
│          (Natural Language → Actions)           │
└─────────────────┬───────────────────────────────┘
                  │ Python API (client/)
    ┌─────────────┴──────────────┐
    │      QGISAgent Client      │
    │   • Multi-service support  │
    │   • Tool auto-selection    │
    │   • OpenAI integration     │
    └─────────────┬──────────────┘
                  │ MCP Protocol
         ┌────────┴──────────┐
         │  MCP Services      │
         │  (services/)       │
         ├────────────────────┤
         │ 14 Services        │
         │ 333 Tools Total    │
         └────────────────────┘
                  ↓
         QGIS Processing Engine

Two Main Components

Services (services/) - 14 independent MCP services exposing QGIS tools
Client (client/) - LLM-powered agent that consumes these services

🚀 Quick Start: Build Your QGIS Agent

Step 1: Install Dependencies

# Clone the repository
git clone <repository-url>
cd qgisToolMCP

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install client dependencies
pip install openai fastmcp python-dotenv

Step 2: Configure Environment

# Copy environment template
cp .env.example .env

# Edit .env and set your API key
echo "OPENAI_API_KEY=your-api-key-here" >> .env
echo "OPENAI_API_BASE_URL=https://api.openai.com/v1" >> .env  # Optional

Step 3: Run Your First Agent

from client.agent import QGISAgent
import asyncio

async def main():
    # Create agent with desired services
    agent = QGISAgent(
        service_scripts=[
            "services/qgis-vector-geometry-buffer-mcp/src/qgis_vector_geometry_buffer_mcp/server.py",
            "services/qgis-vector-analysis-overlay-mcp/src/qgis_vector_analysis_overlay_mcp/server.py",
        ],
        model="gpt-4-turbo-preview"
    )

    # Connect to services
    await agent.connect()

    # Use natural language to execute QGIS operations
    task = """
    Create a 500 meter buffer around the features in input.shp
    and save the result to output.shp
    """

    async for update in agent.process_task(task):
        print(update, end='', flush=True)

    await agent.disconnect()

asyncio.run(main())

Step 4: Test with Example Script

# Run the intelligent tool selection demo
python client/test_agent.py

📦 Available Services

| Category | Service | Tools | Description | |----------|---------|-------|-------------| | Vector Geometry | qgis-vector-geometry-buffer-mcp | 10 | Buffer, offset operations | | | qgis-vector-geometry-hull-bounds-mcp | 18 | Convex hulls, bounding boxes | | | qgis-vector-geometry-transform-mcp | 34 | Transformations, projections | | | qgis-vector-geometry-vertex-mcp | 19 | Vertex manipulation | | Vector Analysis | qgis-vector-analysis-overlay-mcp | 24 | Spatial analysis, clustering | | | qgis-vector-general-creation-mcp | 47 | Create features, points, grids | | | qgis-vector-polygon-line-mcp | 27 | Polygon/line operations | | | qgis-vector-table-selection-mcp | 44 | Attributes, selection, queries | | Raster | qgis-raster-analysis-mcp | 20 | Raster analysis tools | | | qgis-raster-tools-creation-mcp | 18 | Raster creation, conversion | | GDAL | qgis-gdal-raster-mcp | 28 | GDAL raster processing | | | qgis-gdal-vector-mcp | 21 | GDAL vector processing | | Other | qgis-cartography-plots-mcp | 9 | Cartography, plotting | | | qgis-database-network-mcp | 14 | Database, network analysis |

Total: 333 tools across 14 services

🤖 Client API

Basic Usage

from client.agent import QGISAgent

# Single service
agent = QGISAgent(
    service_scripts="services/qgis-vector-geometry-buffer-mcp/src/qgis_vector_geometry_buffer_mcp/server.py"
)

# Multiple services (recommended)
agent = QGISAgent(
    service_scripts=[
        "services/qgis-vector-geometry-buffer-mcp/src/qgis_vector_geometry_buffer_mcp/server.py",
        "services/qgis-vector-analysis-overlay-mcp/src/qgis_vector_analysis_overlay_mcp/server.py",
    ]
)

Key Methods

# Connect to services
await agent.connect()

# List available tools
tools = agent.list_tools()  # ['buffer', 'convex_hull', ...]

# List connected services
services = agent.list_services()  # ['qgis_vector_geometry_buffer_mcp', ...]

# Execute tool directly
result = await agent.execute_tool('buffer', {
    'input_layer': 'input.shp',
    'distance': 1000,
    'output': 'buffered.shp'
})

# Use natural language (LLM-powered)
async for update in agent.process_task("Create a 1km buffer around features"):
    print(update)

# Disconnect
await agent.disconnect()

Advanced Configuration

agent = QGISAgent(
    service_scripts=[...],
    openai_api_key="your-key",           # Or use OPENAI_API_KEY env var
    model="gpt-4-turbo-preview",         # Or "gpt-3.5-turbo", "qwen-max"
    env={"CUSTOM_VAR": "value"},         # Pass to services
    max_retries=3,                        # Retry failed operations
    verbose=True                          # Detailed logging
)

🛠️ Service Management

Setup Individual Service

# Using management script (recommended)
python3 manage.py install qgis-vector-geometry-buffer-mcp

# Configure QGIS environment
cd services/qgis-vector-geometry-buffer-mcp
cp .env.example .env
# Edit .env to set QGIS_PYTHON_PATH and QGIS_PREFIX_PATH

# Test service standalone
python3 manage.py run qgis-vector-geometry-buffer-mcp

Management Commands

# List all services
python3 manage.py list

# View statistics
python3 manage.py stats

# Validate service
python3 manage.py validate <service-name>

See python3 manage.py help or make help for more commands.

🎯 Use Cases

1. Automated GIS Processing

task = """
Process this spatial data:
1. Create 1000m buffer around input.shp
2. Clip with boundary.shp
3. Calculate area statistics
4. Save to output.shp
"""
async for update in agent.process_task(task):
    print(update)

2. Interactive GIS Assistant

# Ask questions
await agent.process_task("What buffer operations are available?")

# Get recommendations
await agent.process_task("Which tool should I use to simplify polygons?")

3. Batch Processing

files = ['file1.shp', 'file2.shp', 'file3.shp']
for file in files:
    await agent.process_task(f"Create 500m buffer around {file}")

📋 Requirements

For Using Services (QGIS operations)

Python 3.10-3.11
QGIS 3.22+ with Python bindings
uv package manager

For Client Only (Agent development)

Python 3.10+
OpenAI API key (or compatible API)
Dependencies: openai, fastmcp, python-dotenv

🧪 Examples

Example 1: Buffer Analysis

# Configure paths in test_agent.py
python client/test_agent.py

Example 2: Custom Agent

See client/agent.py for a complete working example with:

Multi-service connection
Natural language understanding
Intelligent tool selection
Error handling and retries

📖 Documentation

Client README - Detailed client API documentation
Service READMEs - Individual service documentation
Development Guide - Build new services
Architecture Details - System design

🔧 Advanced Topics

Adding More Services

# Load all 14 services for maximum capability
agent = QGISAgent(
    service_scripts=[
        "services/qgis-vector-geometry-buffer-mcp/src/qgis_vector_geometry_buffer_mcp/server.py",
        "services/qgis-vector-geometry-hull-bounds-mcp/src/qgis_vector_geometry_hull_bounds_mcp/server.py",
        # ... add more services
    ]
)

Custom Model Configuration

# Use different models
agent = QGISAgent(
    service_scripts=[...],
    model="gpt-3.5-turbo",  # Faster, cheaper
    # model="gpt-4-turbo-preview",  # More capable
    # model="qwen-max",  # Alternative provider
)

Tool Name Conflicts

When multiple services provide the same tool name, the client automatically prefixes them:

# Original: 'buffer' from multiple services
# Becomes: 'buffer' (first service) and 'service_name__buffer' (others)

🤝 Contributing

Contributions welcome!

Fork the repository
Create your feature branch
Add new services or improve the client
Submit a pull request

See DEVELOPMENT.md for guidelines.

📝 License

MIT License - feel free to use in your projects!

🌟 Getting Help

Check Issues for common problems
Read Documentation for detailed guides
Run python client/test_agent.py for a working example

Ready to build your QGIS agent? Start with python client/test_agent.py 🚀

MCP Servers