Pular para o conteúdo
AI Agent
QGIS
Guia

O que é QGIS MCP? Instalação, limites e alternativa

Publicado em Atualizado em

O QGIS MCP é um plugin gratuito do QGIS, mais um pequeno programa no seu computador, que permite a um app de IA fora do QGIS, em geral o Claude Desktop ou o Claude Code, controlar o QGIS. Você escreve no app de IA, ele envia comandos ao QGIS por uma conexão local e o QGIS os executa: carregar camadas, rodar ferramentas de Processamento, estilizar o mapa ou executar código Python.

Duas linhas comparam arquiteturas. Linha de cima, QGIS MCP, quatro partes que você instala, configura e inicia: um cliente de IA como Claude Desktop, Claude Code ou Cursor, com plano próprio, que fala por stdio com um servidor MCP, um processo Python iniciado pelo uv com uvx qgis-mcp-server, que fala por TCP na porta 9876 com o plugin QGIS MCP, um servidor de socket dentro do QGIS onde você clica em Run MCP a cada sessão, e que controla o seu projeto do QGIS. Linha de baixo, AI Agent, um único plugin: o painel do AI Agent acoplado no QGIS, instalado pelo gerenciador de complementos, que enxerga camadas, campos, SRC, extensão e seleção, e fala por HTTPS com um serviço de agente que roda o modelo na Europa, sem chave de API nem app cliente, e que controla o seu projeto do QGIS.
Em cima: as quatro partes que o QGIS MCP precisa ter rodando juntas. Embaixo: um plugin de agente que vive dentro do QGIS, no caso o nosso.

A ideia é boa e o plugin é bem feito. Nicolas Karasiak mantém a versão do repositório oficial de plugins do QGIS, que tinha 52.575 downloads em 26 de setembro de 2026. O que os tutoriais não contam é quanto trabalho dá para colocá-lo para funcionar e onde ele para. Eu instalei do zero e depois dei a mesma tarefa a ele e a um agente que vive dentro do QGIS. Nós desenvolvemos esse segundo, o AI Agent, então leia minhas conclusões sabendo disso.

O que é MCP, em um parágrafo

MCP, o Model Context Protocol, é um padrão aberto criado pela Anthropic que permite a apps de IA usar ferramentas externas. A introdução oficial o chama de “uma porta USB-C para aplicativos de IA”. O app de IA é o cliente. Um servidor oferece ferramentas a ele. O QGIS MCP é um servidor cujas ferramentas são ações do QGIS. O protocolo descreve o risco sem rodeios: “As ferramentas representam execução arbitrária de código e devem ser tratadas com a devida cautela.”

Como o QGIS MCP funciona

Quatro peças precisam estar instaladas e rodando ao mesmo tempo:

  1. Um cliente MCP: o app de IA em que você escreve, como Claude Desktop, Claude Code, Cursor, VS Code, Codex CLI ou Gemini CLI.
  2. O servidor MCP: um pequeno programa Python que o cliente inicia em segundo plano pelo uv, uma ferramenta que instala e executa programas Python. Você instala o uv antes.
  3. O plugin QGIS MCP: dentro do QGIS, ele escuta os comandos em uma porta de rede local, a 9876. Você clica em Run MCP no botão da barra de ferramentas do plugin para iniciá-lo.
  4. O próprio QGIS, com o seu projeto aberto.

Quando você escreve um pedido, o modelo de IA escolhe uma ferramenta do QGIS, o servidor repassa a chamada ao plugin e o plugin a executa no QGIS e devolve o resultado. O modelo não vê a sua tela. Ele só vê o mapa quando pede ao QGIS uma imagem dele.

O que você precisa antes de começar

RequisitoPara quêCusto
QGIS 3.28 ou posteriorMínimo exigido pelo pluginGrátis
Um app cliente MCPOnde você conversa com o modeloPlano gratuito com limites diários, ou plano pago
uv (executor de pacotes Python)Inicia o servidor MCPGrátis, instala com um comando no terminal
Um comando no terminal ou uma linha em um arquivo de configuraçãoDiz ao cliente onde está o servidorGrátis, mas feito à mão
O plugin QGIS MCPO lado do QGIS na ponteGrátis

Um guia de instalação muito lido diz que você precisa de uma conta paga do Claude Pro. Não precisa. A documentação da Anthropic sobre servidores MCP locais não cita nenhum plano, e um blogueiro de SIG rodou o QGIS MCP no plano gratuito do Claude em agosto de 2026, esbarrando apenas no limite diário de mensagens. Com o ChatGPT é mais difícil. A central de ajuda da OpenAI diz que ele só se conecta a servidores MCP na internet, não a um servidor no seu computador, e que o modo desenvolvedor exigido é restrito a planos pagos.

Instalando o QGIS MCP, com cronômetro

Instalei o QGIS MCP 0.15.0 no QGIS 3.44 em 26 de setembro de 2026 e anotei cada etapa. A página do próprio plugin é franca sobre isso: “Este plugin é apenas metade da instalação. Você também precisa do servidor MCP qgis-mcp, que o seu cliente MCP executa para falar com o QGIS.”

  1. Instale o plugin

    Complementos > Gerenciar e Instalar Complementos, procure por QGIS MCP e clique em Instalar complemento. Esta parte é rápida: ele carregou em 2,7 segundos, sem reiniciar.

  2. Instale o uv

    O servidor roda pelo uv, que o Windows e o macOS não trazem. Você o instala com um comando no terminal.

  3. Escolha um cliente MCP

    Claude Code, Claude Desktop, Cursor, Codex, Gemini CLI ou outro app que fale MCP, com conta e plano próprios.

  4. Conecte o cliente ao QGIS

    O Configurator do plugin mostra um comando para colar no terminal, como claude mcp add -s user qgis -- uvx ... qgis-mcp-server. Alguns clientes pedem, em vez disso, uma linha adicionada a um arquivo de configurações.

  5. Inicie o servidor no QGIS

    Clique em Run MCP no botão da barra de ferramentas do plugin. O QGIS registra “Token authentication disabled (open)” ao iniciar.

  6. Envie a primeira mensagem

    A primeira chamada baixa o servidor, cerca de 90 MB, e só então conecta. Levou 16 segundos no meu teste, e o cliente enxergou 125 ferramentas do QGIS.

O Configurator, na captura de tela abaixo, é onde você escolhe o cliente e copia o comando do terminal.

À esquerda: a página do QGIS MCP 0.15.0, de Nicolas Karasiak, no gerenciador de complementos do QGIS, com 387 votos e 52.575 downloads, e uma descrição que diz que o plugin é apenas metade da instalação e que também é preciso o servidor MCP qgis-mcp. À direita: a janela Setup and Configurator do plugin, com claude-code selecionado como cliente, o status Server running on port 9876 e um comando para rodar no terminal que começa com claude mcp add.
A página do plugin e o Configurator dele. O lado do QGIS é rápido; o resto acontece em um terminal e em outro app.

Minha instalação levou cerca de três minutos, mas o uv e um cliente já estavam instalados e um script fazia os cliques. Na primeira vez, uma pessoa ainda lê a documentação, instala o uv e um cliente e digita o comando.

Uma parte volta todos os dias. Depois de reiniciar o QGIS, o servidor fica desligado, a menos que você marque a inicialização automática no Configurator. O app de IA então só diz “Error executing tool ping”, e você precisa adivinhar que a solução é clicar em Run MCP de novo.

A mesma tarefa, dos dois jeitos

Dei o mesmo pedido às duas ferramentas, ao mesmo tempo no mesmo computador, cada uma em um projeto novo do QGIS: “Em Lyon, na França, encontre as escolas a até 300 metros de uma parada de bonde, mostre-as em um mapa com as linhas de bonde e diga quantas são.”

QGIS MCP, com Claude CodeAI Agent
Tempo até a resposta9 min 28 s5 min 35 s
Etapas10, das quais 6 eram código Python40, das quais 2 eram código Python
Dados usadosOpenStreetMap, baixados por um Python que ele escreveuAs camadas oficiais de escolas, colégios e liceus da Métropole de Lyon, mais paradas e trilhos de bonde do OpenStreetMap
Escolas contadas8780 (52 primárias, 14 colégios, 14 liceus)

As contagens diferem porque as duas ferramentas usaram dados diferentes. O QGIS MCP contou escolas do OpenStreetMap perto de paradas de bonde tiradas de uma caixa em volta de Lyon, então algumas paradas logo fora da cidade também entram, e ele mesmo disse que as 87 não estavam sem duplicatas. O AI Agent usou os cadastros oficiais de escolas da cidade e o limite da comuna de Lyon.

Como chegaram lá é a diferença maior. O QGIS MCP não tem uma ferramenta de dados, então o modelo escreveu código Python para consultar os servidores Overpass do OpenStreetMap. Eles responderam com erros (406, 504 e depois 502 duas vezes), e ele tentou de novo. Esse Python rodou na thread principal do QGIS, então o QGIS ficou travado por cerca de sete minutos, e o mapa ficou vazio até 7 min 22 s.

QGIS depois da execução do QGIS MCP em Lyon: pontos vermelhos para as escolas a até 300 m de uma parada de bonde, linhas de bonde azuis e paradas de bonde cinza sobre fundo branco, sem mapa base. O painel Camadas lista schools_within_300m, tram_lines, tram_stops e uma camada schools_all oculta.
QGIS MCP com Claude Code: 9 min 28 s, 87 escolas, cada download escrito em Python.

O AI Agent buscou primeiro no catálogo de dados e carregou as camadas oficiais de escolas da cidade. Quando o feed nacional de transporte não identificou os bondes de Lyon, ele trocou para o OpenStreetMap nas paradas e trilhos de bonde. Escreveu Python duas vezes, para medir a distância de cada escola até a parada mais próxima.

QGIS com o painel do AI Agent à direita. O mapa mostra o contorno da comuna de Lyon, os trilhos de bonde e as escolas a até 300 m de uma parada, com o nome como rótulo e coloridas como escolas primárias, colégios e liceus. A resposta do agente mostra um cartão de estatísticas com 80 escolas (52 primárias, 14 colégios, 14 liceus) e distâncias até a parada mais próxima de 14,6 a 297,2 m, depois suas fontes: escolas da Métropole de Lyon, paradas e trilhos de bonde do OpenStreetMap, o limite de Lyon e um extrato GTFS.
AI Agent: 5 min 35 s, 80 escolas, a partir das camadas de escolas da própria cidade.

Mais três tarefas, e uma em que o QGIS MCP foi mais rápido

Uma corrida prova pouco, então cronometrei mais três tarefas do mesmo jeito. Nem todas favorecem a nós:

TarefaQGIS MCP, com Claude CodeAI Agent
Edificações do centro histórico do Porto por tipo, sobre mapa base de satélite1 min 44 s1 min 21 s
O mesmo, mais um layout em PDF A4 com título, legenda, barra de escala e seta do norte2 min 48 s5 min 26 s
Edificações em York sob risco de inundação de rio, com dados da Environment AgencyNão terminou em 15 min, nada no mapaNão terminou em 15 min, parte dos dados de inundação carregou, sem contagem

Quando os dados estão a um download do OpenStreetMap de distância, o QGIS MCP acompanha, e no layout em PDF foi cerca de duas vezes mais rápido. A própria resposta dele avisou que exportou o PDF sem conferir se os blocos de satélite tinham carregado. A diferença aparece quando o modelo precisa encontrar e baixar os dados sozinho, como em Lyon. Nenhuma das ferramentas terminou a tarefa de inundação de York em 15 minutos. Uma primeira execução no Porto, em 26 de setembro, levou 8 min 29 s no QGIS MCP porque os servidores de download estavam sobrecarregados naquele dia, então cronometrei tudo de novo.

Como medimos. Mesmo computador, as duas ferramentas rodando ao mesmo tempo, QGIS 3.44.15, projeto novo e configurações padrão, exceto o esforço do AI Agent, definido como Medium. Uma execução cada, sem novas tentativas: QGIS MCP 0.15.2 conduzido pelo Claude Code no Claude Sonnet 5.5, com apenas as ferramentas do QGIS permitidas, e AI Agent 1.9.0 no modo Balanced. O tempo do QGIS MCP é o tempo de execução do próprio Claude Code, que deixa de fora os 52 segundos que o cliente levou para iniciar. O computador estava muito carregado e os servidores do OpenStreetMap estavam falhando para as duas ferramentas durante a corrida de Lyon. Filmamos todas as execuções.

Você pode enviar o mesmo pedido no seu QGIS em poucos minutos: instale o plugin, entre na sua conta e cole o pedido no painel.

Onde o QGIS MCP fica devendo

Estes são os limites que encontrei ou que estão documentados, cada um com sua fonte:

  • O chat fica fora do QGIS. Você alterna entre duas janelas. O modelo trabalha a partir dos resultados das ferramentas e só vê o mapa quando pede uma imagem dele ao QGIS.
  • Quatro peças móveis. Quando nada acontece, a falha pode estar nas configurações do cliente, no uv, no servidor, na porta ou no plugin. A página de solução de problemas do projeto lista “No response from QGIS”, Connection refused e ModuleNotFoundError como os erros mais comuns.
  • Uma armadilha no Windows. O README avisa que o Claude Desktop instalado pela Microsoft Store roda os servidores em um sandbox que quebra a configuração habitual, então uma configuração que funciona em outros lugares falha ali.
  • Qualquer Python, sem senha por padrão. A ferramenta execute_code executa qualquer PyQGIS (o código Python do QGIS) que o modelo escrever. O README diz isso: “By default the socket has no authentication... any process on the machine that can reach the port can drive QGIS (including execute_code, which runs arbitrary PyQGIS).” Um fork, o QGIS Agent MCP, existe principalmente para remover essa ferramenta.
  • Sem dados próprios. Ele controla o QGIS, mas encontrar e baixar dados fica por conta do modelo, em geral escrevendo Python. No teste de Lyon, 6 das 10 etapas foram Python, e os downloads travaram o QGIS por cerca de sete minutos.
  • Sem desfazer um pedido inteiro. O desfazer do QGIS cobre edições, não camadas adicionadas nem arquivos gravados.
  • A cópia com mais estrelas não é a mantida. O original no GitHub, jjsantos01/qgis_mcp, tem 1.099 estrelas, nenhuma alteração de código desde 1º de outubro de 2025 e uma issue aberta chamada “Broken plugin for QGIS version 4.01”. A versão mantida, nkarasiak/qgis-mcp, é a do repositório de plugins do QGIS.

Onde a web erra sobre o assunto

“Você precisa do Claude Pro.” Servidores MCP locais funcionam no plano gratuito do Claude, dentro dos limites diários. A exigência de plano pago está no ChatGPT, que de qualquer forma não alcança diretamente um servidor no seu computador.

“Reinicie o computador depois de editar a configuração.” Basta reiniciar o app cliente. No Windows, confirme que ele fechou por completo, já que continua rodando na bandeja do sistema.

“Instale o repositório com mais estrelas.” Instale pelo gerenciador de complementos do QGIS, que entrega a versão mantida.

Outras formas de conectar o Claude ao QGIS

O plugin acima é o que a maioria dos guias tem em mente, mas outros três projetos também colocam o Claude no QGIS. Lidos nas próprias páginas deles em 23 de outubro de 2026:

  • piatkowski/qgis-mcp: um projeto separado com o mesmo nome, feito para o Claude Desktop. Instala por um ZIP na página de releases do GitHub, e não pelo gerenciador de complementos, exige Python 3.12 ou posterior para o servidor e começa a escutar na porta 9876 assim que o plugin é ativado. O plugin acima também usa a porta 9876, então rode um de cada vez.
  • ClaudIA QGIS: derivado do plugin acima, com a porta local trocada por uma conexão HTTPS com a comunidade agrônomo10X, então não há Python para instalar. Exige uma conta agrônomo10X, e a versão 0.2.3, de 15 de setembro de 2026, está marcada como experimental.
  • QGIS Agent: um painel de chat dentro do QGIS com a sua própria chave de LLM, e um servidor MCP local opcional que o Claude Desktop ou o Cursor podem controlar.

Uma alternativa ao QGIS MCP: um agente dentro do QGIS

Nós desenvolvemos o AI Agent, então esta seção é sobre o nosso próprio plugin. Ele faz o mesmo trabalho do QGIS MCP de dentro do QGIS: o chat é um painel acoplado ao lado do mapa e o modelo já vem com o plugin. Nos benchmarks GeoKTools e GeoExpertQueries do Google, o Claude Sonnet 5.5 conduzindo o QGIS por este plugin QGIS MCP (versão 0.15.1, no Claude Code) fez 24,9 de 100 em 41 perguntas reservadas, e o AI Agent no esforço Low (GPT-6 Luna) fez 43,8 (os resultados do benchmark).

As diferenças que pesam no dia a dia:

  • Uma instalação só. Complementos > Gerenciar e Instalar Complementos, procure por AI Agent by TerraLab, instale e entre na sua conta. Sem uv, sem arquivo de configuração, sem app separado, sem servidor para iniciar a cada sessão.
  • Ele enxerga o seu projeto. Nomes de camadas, campos, SRC, extensão e seleção vão junto com cada pedido, e ele renderiza o mapa para conferir o próprio trabalho.
  • Dados embutidos. Um catálogo de 190 fontes de dados abertos, do OpenStreetMap ao Sentinel-2 e a órgãos nacionais de mapeamento, para que o modelo não precise escrever código de download.
  • Ele pergunta antes. Na configuração padrão, ele para antes de apagar ou sobrescrever, e o Python que altera o seu projeto sempre precisa do seu clique.
  • Desfazer por mensagem. Cada mensagem deixa um ponto de restauração, e um clique devolve o projeto a ele.

Ele precisa de conexão com a internet e envia uma descrição do seu projeto, nunca os seus arquivos de dados, para um serviço hospedado na Europa. Existe um plano Free sem cartão, e uma mensagem conta como uma execução, não importa quantas etapas ela tenha. Experimente o Pro grátis por 7 dias: adicione um cartão, cancele antes do fim e nada é cobrado.

Teste o AI Agent grátis no QGIS, sem cartão

QGIS MCP ou um agente dentro do QGIS, lado a lado

QGIS MCPAI Agent
Onde você conversaEm um app externo (Claude Desktop, Cursor, Claude Code)Em um painel dentro do QGIS
O que você instalaO plugin, o uv, um cliente MCP, uma entrada de configuraçãoUm plugin
A cada sessãoIniciar o servidor no QGIS e manter os dois apps abertosAbrir o painel
ModeloO que o seu cliente usar, no seu planoIncluído
Catálogo de dados abertosNão190 fontes
Executa PythonSim, sem perguntar por padrãoPergunta antes de código que altera o projeto
Desfazer um pedido inteiroNãoSim, com um clique
PreçoPlugin grátis, mais o seu plano de IAPlano Free, depois Pro a € 49 por mês
Ideal paraDesenvolvedores que já trabalham no Claude Code ou no CursorUsuários de SIG que querem o resultado no QGIS

Qual usar?

Se você já trabalha no Claude Code ou no Cursor, escreve Python e quer o QGIS como mais uma ferramenta ali, o QGIS MCP é uma boa escolha e não custa nada além do plano de IA que você já paga. Se você quer escrever uma tarefa de geoprocessamento e receber o resultado no seu projeto, sem terminal, sem uv e sem um segundo app, um agente dentro do QGIS chega lá com menos para instalar e manter. Esse segundo caso é o da maioria dos usuários de SIG que conheço.

O que guardar

O QGIS MCP conecta um app de IA fora do QGIS, como o Claude Desktop, ao QGIS por uma conexão local, para que o modelo do app possa executar ferramentas do QGIS e código Python.

Ele precisa de quatro partes rodando juntas: o app cliente, o uv com o servidor MCP, o plugin QGIS MCP com o servidor iniciado e o QGIS.

O lado do QGIS instala em segundos. O resto acontece fora dele: instalar o uv, um app de IA, rodar um comando no terminal e clicar em Run MCP de novo a cada reinício.

Na tarefa de Lyon, o AI Agent respondeu em 5 min 35 s a partir das camadas oficiais de escolas da cidade. O QGIS MCP levou 9 min 28 s e escreveu Python em 6 de suas 10 etapas. Em tarefas mais simples a diferença diminui, e em um layout em PDF o QGIS MCP foi mais rápido.

O ChatGPT não consegue usar um servidor MCP local diretamente. O plano gratuito do Claude funciona, dentro dos limites diários.

Um agente dentro do QGIS, como o AI Agent, faz o mesmo trabalho com um único plugin, com modelo, catálogo de dados e desfazer com um clique incluídos.

Perguntas frequentes

O que é um agente de IA no QGIS conta os 38 plugins de agente e de assistente do repositório oficial, incluindo as pontes MCP. O guia do AI Agent mostra dez execuções reais com seus prompts, e o PyQGIS mede com que frequência o código escrito por chatbots roda de primeira. O hub de IA para QGIS compara o restante do cenário.

Faça no QGIS só pedindo

O AI Agent executa a tarefa que você descreve, no seu próprio projeto QGIS. Grátis, sem cartão.

Experimente o AI Agent grátis
Escrito porYvann Barbot
·21 min read

Continue lendo