QGIS MCP Multi-Service Architecture

A Model Context Protocol (MCP) server suite that exposes 333 QGIS processing tools through 14 specialized services.

This project has been refactored from a monolithic architecture into 14 independent MCP services, with each service containing ≤50 tools to optimize LLM context usage.

✨ Features

• 🎯 14 Independent Services - Split by functional domain, each service ≤ 50 tools
• 🔧 Modular Design - Load services as needed
• ✅ Complete Implementation - All 14 services fully implemented (333 tools)
• 🛠️ Management Tools - Convenient manage.py and Makefile
• 📚 Complete Documentation - Detailed documentation for each service

🚀 Quick Start

Install and Run Example 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

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

Using Makefile

make install SERVICE=qgis-vector-geometry-buffer-mcp
make run SERVICE=qgis-vector-geometry-buffer-mcp

🛠️ Management Tools

Common Commands

# List all services
python3 manage.py list

# View statistics
python3 manage.py stats

# Install/run service
python3 manage.py install <service-name>
python3 manage.py run <service-name>

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

More commands: python3 manage.py help or make help

📋 Requirements

• Python 3.10-3.11 (MCP service)
• QGIS 3.22+ (with Python bindings)
• uv package manager

QGIS Configuration

Each service requires .env file configuration:

QGIS_PYTHON_PATH=/usr/bin/python3
QGIS_PREFIX_PATH=/usr

QGIS Documentation (Optional)

Only needed when implementing new tools. See docs/README.md for documentation acquisition guide.

📖 Documentation

• Development Guide - How to implement new services and tools
• Project Transformation - Complete refactoring process
• Splitting Plan - Detailed service splitting design
• Service READMEs - Detailed documentation for each service

🏗️ Architecture

AI Assistant (Claude)
    ↓ MCP Protocol
MCP Service (FastMCP)
    ↓ subprocess
QGIS Python Environment
    ↓
QGIS Processing Algorithm

14 independent services, each focusing on a specific functional domain, supporting on-demand loading.

🤝 Contributing

Contributions welcome! Please refer to documentation/DEVELOPMENT.md to learn how to implement new services.

Prioritize high-priority (⭐⭐⭐) services.

📝 License

MIT License

Get Started: Run python3 manage.py list to view all available services