Qgistoolmcp

🚀 QGIS MCP Services - LLM-Powered Geospatial Processing Framework

A comprehensive framework for constructing LLM-powered QGIS agents, equipped with 333 geospatial processing tools across 14 specialized MCP services.

Leverage AI agents to convert natural language into automated QGIS workflows, with intelligent selection and execution of appropriate geospatial tools.

🚀 Quick Start

1. Prerequisites

• Python 3.10 - 3.11
• QGIS 3.22+ with Python bindings installed
• Virtual environment (recommended)

2. Installation

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

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

# Install all services
pip install -e services/qgis-vector-geometry-buffer-mcp/
pip install -e services/qgis-vector-analysis-overlay-mcp/
# ... install other services as needed

# Install client demo dependencies
pip install openai mcp python-dotenv

3. Configure Environment

# Create environment file
cp .env.example .env

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

4. Start Services

# Start all 14 services in the background
cd services
./run.sh

# Check service status
./status.sh

# View logs for a specific service
tail -f logs/qgis-vector-geometry-buffer-mcp.log

5. Run the Demo Agent

# Run the LLM-powered agent demo
python client_demo/agent.py http://localhost:32821/sse http://localhost:32822/sse

# Or run the test script
python client_demo/test_agent.py

✨ Features

• 🤖 LLM-Powered Agent: Translate natural language into QGIS operations with intelligent tool selection.
• 🎯 333 QGIS Tools: Access a complete QGIS processing toolkit via the Model Context Protocol (MCP).
• 🔧 14 Specialized Services: Cover vector, raster, GDAL, cartography, and more.
• 🌐 HTTP SSE Communication: All services are accessible via Server-Sent Events.
• 📦 Modular Architecture: Load only the services you need.
• 🛠️ Simple Python API: Facilitate easy integration for custom agent development.
• 🔌 Background Service Management: Use scripts to start, stop, and check the status of all services.

🔧 Technical Details

Architecture

┌─────────────────────────────────────────────────┐
│          LLM-Powered QGIS Agent                 │
│      (Natural Language → Tool Selection)        │
│              (client_demo/agent.py)             │
└─────────────────┬───────────────────────────────┘
                  │ HTTP SSE
    ┌─────────────┴──────────────┐
    │   14 Independent Services   │
    │  (services/qgis-*-mcp/)     │
    ├─────────────────────────────┤
    │ Each service runs on its    │
    │ own port (32821-32834)      │
    └─────────────┬───────────────┘
                  │
         QGIS Processing Engine
          (via shared executor)

💻 Usage Examples

Basic Usage

Example 1: Using the LLM-Powered Agent

import asyncio
from client_demo.agent import QGISAgent

async def main():
    # Create agent connected to multiple services
    agent = QGISAgent(
        service_urls=[
            "http://localhost:32821/sse",  # buffer service
            "http://localhost:32822/sse",  # hull-bounds service
            "http://localhost:32824/sse",  # analysis-overlay service
        ],
        model="gpt-4-turbo-preview"
    )

    # Connect to services
    await agent.connect()

    # Use natural language to describe the task
    task = """
    I have a shapefile at /path/to/input.shp with point features.
    Please create a 500 meter buffer around each point and save
    the result to /path/to/output.shp
    """

    # Agent will intelligently select and execute the right tool
    async for update in agent.process_task(task):
        print(update, end='', flush=True)

    await agent.disconnect()

asyncio.run(main())

Advanced Usage

Example 2: Direct Tool Execution

import asyncio
from client_demo.agent import QGISAgent

async def main():
    agent = QGISAgent(
        service_urls="http://localhost:32821/sse"
    )

    await agent.connect()

    # Execute a specific tool directly
    result = await agent.execute_tool('buffer', {
        'INPUT': '/path/to/input.shp',
        'DISTANCE': 500,
        'OUTPUT': '/path/to/output.shp'
    })

    print(f"Result: {result}")

    await agent.disconnect()

asyncio.run(main())

Example 3: Interactive Mode

# Run the agent in interactive mode
python client_demo/agent.py http://localhost:32821/sse

# Then type natural language queries:
# > Create a 1km buffer around the features in my_layer.shp
# > Simplify the geometries with tolerance 0.5
# > Calculate the area of each polygon

📦 Available Services

Total: 333 tools across 14 services

📚 Documentation

Service Management

Start All Services

cd services
./run.sh

This starts all 14 services in the background with logging.

Check Service Status

cd services
./status.sh

Output example:

Service: qgis-vector-geometry-buffer-mcp    Status: RUNNING  PID: 12345  Port: 32821
Service: qgis-vector-geometry-hull-bounds-mcp  Status: RUNNING  PID: 12346  Port: 32822
...

Stop All Services

cd services
./stop.sh

View Logs

# View logs for a specific service
tail -f services/logs/qgis-vector-geometry-buffer-mcp.log

# View all logs
tail -f services/logs/*.log

# Search for errors
grep -i error services/logs/*.log

Client Demo API

The client_demo/agent.py provides a powerful agent framework:

QGISAgent Class

agent = QGISAgent(
    service_urls: List[str] | str,  # Service URL(s) to connect to
    openai_api_key: Optional[str] = None,  # OpenAI API key
    base_url: Optional[str] = None,  # API base URL
    model: str = "gpt-4-turbo-preview",  # LLM model to use
    max_retries: int = 3,  # Retry attempts for failed operations
    verbose: bool = True  # Enable detailed logging
)

Key Methods

• await agent.connect(): Connect to all services
• await agent.disconnect(): Disconnect from services
• agent.list_tools(): Get list of all available tools
• agent.list_services(): Get list of connected services
• agent.list_tools_by_service(): Get tools grouped by service
• await agent.execute_tool(name, params): Execute a specific tool
• async for update in agent.process_task(description): Process natural language task

Project Structure

qgisToolMCP/
├── client_demo/              # LLM-powered agent demo
│   ├── agent.py             # Main QGISAgent class
│   ├── test_agent.py        # Test script
│   ├── test_direct_call.py  # Direct call example
│   └── data/                # Test data
├── services/                 # 14 independent MCP services
│   ├── run.sh               # Start all services
│   ├── stop.sh              # Stop all services
│   ├── status.sh            # Check service status
│   ├── logs/                # Service logs (created at runtime)
│   ├── pids/                # Service PID files (created at runtime)
│   └── qgis-*-mcp/          # Individual services
│       ├── src/             # Service source code
│       ├── docs/            # Service documentation
│       ├── pyproject.toml   # Service configuration
│       └── README.md        # Service-specific docs
├── shared/                   # Shared code across services
│   ├── executor.py          # QGIS algorithm executor
│   └── qgis_runner.py       # QGIS Python runner script
├── documentation/            # Project documentation
│   ├── DEVELOPMENT.md       # Development guide
│   ├── PROJECT_TRANSFORMATION.md  # Architecture overview
│   └── README.md            # Documentation index
├── scripts/                  # Utility scripts
├── manage.py                 # Service management CLI
├── Makefile                  # Build automation
└── README.md                 # This file

Development

Adding a New Tool to a Service

1. Navigate to the service directory:

cd services/qgis-vector-geometry-buffer-mcp/src/qgis_vector_geometry_buffer_mcp/tools/

2. Add your tool function:

@mcp.tool()
def my_new_tool(
    input_layer: str,
    parameter: float,
    output: str
) -> dict:
    """Tool description"""
    params = {
        'INPUT': input_layer,
        'PARAMETER': parameter,
        'OUTPUT': output
    }
    result = executor.run_algorithm('native:algorithm_id', params)
    return {
        "output": result.get('OUTPUT'),
        "status": "success"
    }

3. Register the tool in tools/__init__.py

4. Restart the service:

cd services
./stop.sh
./run.sh

See DEVELOPMENT.md for detailed development guide.

Configuration

Environment Variables

Create a .env file in the project root:

# OpenAI API Configuration
OPENAI_API_KEY=your-api-key-here
OPENAI_API_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4-turbo-preview

# QGIS Configuration (for services)
QGIS_PYTHON_PATH=/usr/bin/python3
QGIS_PREFIX_PATH=/usr

Service Configuration

Each service can have its own .env file in its directory for service-specific configuration.

Requirements

For Running Services

• Python 3.10 - 3.11
• QGIS 3.22+ with Python bindings
• Required Python packages (installed automatically):
  • fastmcp
  • python-dotenv

For Using the Agent

• Python 3.10+
• OpenAI API key (or compatible API)
• Required Python packages:
  • openai
  • mcp
  • python-dotenv

Troubleshooting

Services Won't Start

1. Check if QGIS is properly installed:

python3 -c "from qgis.core import QgsApplication; print('QGIS OK')"

2. Check service logs:

tail -f services/logs/<service-name>.log

3. Verify virtual environment:

which python
# Should point to .venv/bin/python

Port Conflicts

If you get "port already in use" errors, you can:

1. Check what's using the port:

lsof -i :32821

2. Kill the process or change the port in services/run.sh

Agent Can't Connect to Services

1. Verify services are running:

cd services
./status.sh

2. Check if ports are accessible:

curl http://localhost:32821/sse

3. Verify service URLs in your agent code match the running services

Other Documentation

• Development Guide: How to develop new services and tools
• Project Transformation: Architecture and design decisions
• Service Management: Detailed service management documentation
• Client Demo: Agent usage and examples
• Shared Code: Shared utilities documentation

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. Add New Tools: Implement additional QGIS algorithms
2. Improve Documentation: Enhance guides and examples
3. Fix Bugs: Report and fix issues
4. Optimize Performance: Improve execution speed
5. Add Tests: Increase test coverage

See DEVELOPMENT.md for contribution guidelines.

📄 License

MIT License - See LICENSE file for details

🙏 Acknowledgments

• Built on FastMCP framework
• Uses QGIS processing algorithms
• Powered by Model Context Protocol (MCP)

🛠️ Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

Built with ❤️ for the geospatial AI community