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.

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:
- Um cliente MCP: o app de IA em que você escreve, como Claude Desktop, Claude Code, Cursor, VS Code, Codex CLI ou Gemini CLI.
- 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 ouvantes. - 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.
- 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
| Requisito | Para quê | Custo |
|---|---|---|
| QGIS 3.28 ou posterior | Mínimo exigido pelo plugin | Grátis |
| Um app cliente MCP | Onde você conversa com o modelo | Plano gratuito com limites diários, ou plano pago |
uv (executor de pacotes Python) | Inicia o servidor MCP | Grátis, instala com um comando no terminal |
| Um comando no terminal ou uma linha em um arquivo de configuração | Diz ao cliente onde está o servidor | Grátis, mas feito à mão |
| O plugin QGIS MCP | O lado do QGIS na ponte | Grá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.”
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.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.Escolha um cliente MCP
Claude Code, Claude Desktop, Cursor, Codex, Gemini CLI ou outro app que fale MCP, com conta e plano próprios.
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.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.
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.

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 Code | AI Agent | |
|---|---|---|
| Tempo até a resposta | 9 min 28 s | 5 min 35 s |
| Etapas | 10, das quais 6 eram código Python | 40, das quais 2 eram código Python |
| Dados usados | OpenStreetMap, baixados por um Python que ele escreveu | As camadas oficiais de escolas, colégios e liceus da Métropole de Lyon, mais paradas e trilhos de bonde do OpenStreetMap |
| Escolas contadas | 87 | 80 (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.

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.

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:
| Tarefa | QGIS MCP, com Claude Code | AI Agent |
|---|---|---|
| Edificações do centro histórico do Porto por tipo, sobre mapa base de satélite | 1 min 44 s | 1 min 21 s |
| O mesmo, mais um layout em PDF A4 com título, legenda, barra de escala e seta do norte | 2 min 48 s | 5 min 26 s |
| Edificações em York sob risco de inundação de rio, com dados da Environment Agency | Não terminou em 15 min, nada no mapa | Nã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 refusedeModuleNotFoundErrorcomo 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_codeexecuta 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. Semuv, 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 MCP | AI Agent | |
|---|---|---|
| Onde você conversa | Em um app externo (Claude Desktop, Cursor, Claude Code) | Em um painel dentro do QGIS |
| O que você instala | O plugin, o uv, um cliente MCP, uma entrada de configuração | Um plugin |
| A cada sessão | Iniciar o servidor no QGIS e manter os dois apps abertos | Abrir o painel |
| Modelo | O que o seu cliente usar, no seu plano | Incluído |
| Catálogo de dados abertos | Não | 190 fontes |
| Executa Python | Sim, sem perguntar por padrão | Pergunta antes de código que altera o projeto |
| Desfazer um pedido inteiro | Não | Sim, com um clique |
| Preço | Plugin grátis, mais o seu plano de IA | Plano Free, depois Pro a € 49 por mês |
| Ideal para | Desenvolvedores que já trabalham no Claude Code ou no Cursor | Usuá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
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.
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.
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.
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.
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.
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, 190 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.
Leia a seguirClaude no QGIS: 3 formas de conectar, testadas na mesma tarefa
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.


