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

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.

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

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.”

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

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, em um projeto novo do QGIS: “Carregue as edificações do centro histórico do Porto, em Portugal, a partir do OpenStreetMap, pinte-as por tipo de edificação, coloque uma imagem de satélite como mapa base por baixo e diga quantas edificações há.”

As duas contagens estão certas para a área que cada ferramenta escolheu, e por isso diferem. O que muda é como cada uma chegou lá. O QGIS MCP não tem uma ferramenta de dados, então o modelo escreveu código Python para baixar os dados do OpenStreetMap. Quando os servidores de download ficaram lentos, as novas tentativas travaram o QGIS por até um minuto de cada vez. Em seu favor, ele percebeu um erro próprio que tinha descartado 37 edificações e o corrigiu.

O AI Agent usou a ferramenta de OpenStreetMap que já vem nele, buscou o limite real do centro histórico, recortou as edificações por esse limite e as estilizou, sem escrever nenhum código. O mapa base de satélite dele fica mais desfocado nesse zoom do que o escolhido pelo QGIS MCP.

Como medimos. Mesmo computador, QGIS 3.44.7, mesmo pedido, projeto novo e configurações padrão, com o QGIS MCP 0.15.0 conduzido pelo Claude Code no Claude Sonnet e o AI Agent 1.4.1. Conferimos as duas contagens nós mesmos, contra o OpenStreetMap para o retângulo e contando a camada final para o limite. Os servidores de download estavam sobrecarregados durante a execução do QGIS MCP, o que lhe custou tempo, e uma primeira tentativa do AI Agent travou o QGIS, um bug que já registramos, por isso os números dele vêm da nova execução.

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.

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

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 meu teste, 17 das 28 ações foram Python, e as novas tentativas de download travaram o QGIS por 40 a 62 segundos de cada vez.
• 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.

A opção mais simples: 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.

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 55 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.

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

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

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 mesma tarefa do Porto, o AI Agent respondeu em 1 min 11 s com 15 ações e nenhum código. O QGIS MCP levou 8 min 29 s e escreveu Python em 17 de suas 28 ações.

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 é o QGIS MCP?

Um plugin do QGIS e um servidor MCP local que permitem a um app de IA controlar o QGIS pelo Model Context Protocol. Você conversa no app, em geral o Claude Desktop ou o Claude Code, e o modelo chama ferramentas do QGIS: carregar camadas, rodar o Processamento, estilizar, renderizar o mapa e executar Python.

Como conectar o Claude ao QGIS?

Instale o plugin QGIS MCP pelo gerenciador de complementos e clique em Run MCP, instale o uv, depois adicione o servidor QGIS MCP ao arquivo de configuração do Claude Desktop, ou rode o comando claude mcp add no Claude Code, e reinicie o cliente. Ou instale um plugin de agente que roda dentro do QGIS com modelo próprio, como o AI Agent, que dispensa o cliente, o uv e a configuração.

O ChatGPT consegue usar o QGIS MCP?

Não diretamente. A central de ajuda da OpenAI diz que o ChatGPT se conecta a servidores MCP na internet, então um servidor no seu computador, como o QGIS MCP, precisaria de um túnel para ser alcançado. O modo desenvolvedor, exigido pelo MCP, é limitado aos planos pagos do ChatGPT.

O QGIS MCP é seguro?

Ele pode executar dentro do QGIS qualquer Python que o modelo escrever e, por padrão, o socket local não tem autenticação, como o próprio README informa. Use-o em uma máquina de confiança, defina o token de segredo compartilhado se outras pessoas usarem a máquina, pare o servidor quando terminar e mantenha backups dos projetos importantes.

Por que o QGIS MCP não conecta?

As causas habituais, segundo o guia de solução de problemas do projeto: o servidor não foi iniciado no QGIS (Connection refused, clique em Run MCP), o uv não está instalado ou não é encontrado (ModuleNotFoundError), ou a porta não é a 9876. Depois de reiniciar o QGIS, o servidor volta a ficar desligado, a menos que a inicialização automática esteja marcada. No Windows, uma instalação do Claude Desktop pela Microsoft Store exige a forma --directory na configuração.

Existe uma alternativa ao QGIS MCP?

Sim. Plugins de agente rodam dentro do QGIS como um painel de chat, sem app externo nem servidor local. Contamos 38 plugins de agente e de assistente no repositório oficial em setembro de 2026. O nosso, o AI Agent, inclui o modelo, 55 fontes de dados abertos e desfazer com um clique, com um plano Free.

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.