Prezado Leitor,

A integração entre Inteligência Artificial e Sistemas de Informação Geográfica (SIG) está evoluindo rapidamente. Hoje já é possível conectar o Claude AI diretamente ao QGIS através do protocolo MCP (Model Context Protocol), permitindo que a IA consulte camadas, execute análises espaciais e automatize tarefas dentro do projeto GIS.

Neste tutorial você aprenderá como configurar o ambiente completo no Windows.

Ao final, você terá o Claude conversando diretamente com o QGIS.

O que é o QGIS MCP?

O QGIS MCP é um servidor que permite que modelos de IA como Claude acessem funcionalidades do QGIS através do protocolo MCP (Model Context Protocol).

Na prática, isso significa que você poderá pedir coisas como:

  • Liste as camadas abertas no projeto.
  • Informe o sistema de coordenadas da camada.
  • Gere um buffer de 500 metros.
  • Execute algoritmos do Processing.
  • Crie estilos para camadas.
  • Consulte atributos.

Tudo isso utilizando linguagem natural.

Pré-requisitos

Antes de começar, você precisará ter:

  • QGIS instalado
  • Conta no Claude AI
  • Claude Desktop
  • Python instalado

Etapa 1 — Criar uma conta no Claude

Acesse: https://claude.ai

Clique em Sign Up e crie sua conta.

Após a criação, faça login normalmente.

Etapa 2 — Instalar o Claude Desktop

Baixe o Claude Desktop diretamente do site oficial: https://claude.ai/download e selecione a versão para Windows.

Após a instalação:

  1. Abra o Claude Desktop.
  2. Faça login com sua conta.
  3. Verifique se o aplicativo abre normalmente.

Feche o Claude antes de continuar.

Etapa 3 — Instalar o UV

O QGIS MCP utiliza o UV para executar o servidor MCP.

Abra o Prompt de Comando do Windows e execute:

pip install uv

Após a instalação, valide:

uv --version

ou

uvx --version

O resultado deverá ser semelhante a:

uvx 0.11.21

Também é interessante verificar onde o executável foi instalado:

where uvx

Exemplo:

C:\Users\Fernando\.local\bin\uvx.exe

Guarde esse caminho, pois ele será utilizado na configuração do Claude.

Etapa 4 — Instalar o plugin QGIS MCP

Abra o QGIS.

Acesse:

Complementos → Gerenciar e Instalar Complementos

Pesquise por:

QGIS MCP

Instale o plugin.

Após a instalação:

  1. Ative o plugin.

  2. Verifique se o servidor está rodando.

O plugin iniciará um serviço local que permitirá ao Claude acessar o QGIS.

Etapa 5 — Configurar o Claude Desktop

O Claude Desktop utiliza um arquivo JSON para registrar servidores MCP.

Localize o arquivo de configuração do Claude.

Ao abrir a tela de configurações, vá na opção Developer (Desenvolvedor), e clique no botão Editar Config.

O Claude irá abrir uma tela do Windows Explorer com o arquivo claude_desktop_config.json selecionado. Você dever editar esse arquivo e inserir a seguinte configuração:

{
  "mcpServers": {
    "qgis": {
      "command": "C:\\Users\\SEU_USUARIO\\.local\\bin\\uvx.exe",
      "args": [
        "--from",
        "https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip",
        "qgis-mcp-server"
      ],
      "env": {
		"PATH": "C:\\Users\\SEU_USUARIO\\.local\\bin;C:\\Windows\\System32;C:\\Windows"
      }
    }
  }
}

Importante:

Substitua o caminho do comando pelo caminho retornado pelo comando:

where uvx

Exemplo:

"command": "C:\\Users\\Fernando\\.local\\bin\\uvx.exe"

Salve o arquivo.

Etapa 6 — Reiniciar os componentes

Após salvar o JSON:

  1. Feche completamente o Claude Desktop.
  2. Abra o QGIS.
  3. Verifique se o plugin QGIS MCP está ativo.
  4. Abra novamente o Claude Desktop.

Caso tudo esteja correto, o Claude deverá carregar automaticamente o servidor MCP do QGIS.

Etapa 7 — Testar a comunicação

Abra um projeto qualquer no QGIS.

Em seguida faça perguntas ao Claude como:

Liste todas as camadas abertas no QGIS.

ou

Qual é o sistema de coordenadas da camada municípios?

ou ainda:

Mostre os atributos da camada escolas.

Se o MCP estiver funcionando corretamente, o Claude responderá utilizando informações diretamente do QGIS.

Diagnóstico de problemas

Erro: Could not attach to MCP server qgis

Esse erro normalmente indica que:

  • O UV não está instalado.
  • O caminho do uvx.exe está incorreto.
  • O JSON está com erro de sintaxe.
  • O plugin QGIS MCP não está ativo.

Testando manualmente o servidor MCP

Abra o Prompt de Comando:

C:\Users\SEU_USUARIO\.local\bin\uvx.exe --from "https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip" qgis-mcp-server

Se tudo estiver correto, deverá aparecer algo semelhante a:

QgisMCPServer starting up
will connect to QGIS at localhost:9876