Skip to content

Tutorial: Conectando o Claude ao QGIS via MCP (QGIS MCP)

Este tutorial cobre a instalação do QGIS MCP (nkarasiak/qgis-mcp), um plugin que conecta o QGIS Desktop ao Claude (ou outros assistentes de IA compatíveis com MCP) através do Model Context Protocol. Uma vez conectado, você pode pedir ao Claude para carregar camadas, editar feições, rodar algoritmos do Processing, gerar mapas, estilizar layers e muito mais — direto em linguagem natural.

Importante: isso só funciona com Claude Desktop (ou Claude Code), não com a interface web/app de chat (claude.ai). A conexão depende de um processo rodando na sua própria máquina.

Como funciona

Claude Desktop ←→ Servidor MCP (fora do QGIS) ←→ socket TCP (porta 9876) ←→ Plugin QGIS (dentro do QGIS) ←→ API do PyQGIS

Dois componentes: 1. Plugin do QGIS — roda dentro do QGIS, abre um servidor socket local. 2. Servidor MCP — roda fora do QGIS, expõe as operações do QGIS como ferramentas MCP para o Claude.

Pré-requisitos (todos os sistemas)

  • QGIS 3.28 ou superior instalado (testado até a série 3.40 / 4.x)
  • Claude Desktop instalado e logado
  • uv/uvx instalado — é o gerenciador que baixa e roda o servidor MCP

Etapa 1 — Instalar o plugin dentro do QGIS (igual nos três sistemas)

  1. Abra o QGIS.
  2. Vá em Complementos → Gerenciar e Instalar Complementos (ou Plugins → Manage and Install Plugins, em inglês).
  3. Na aba Todos, busque por QGIS MCP.
  4. Clique em Instalar.
  5. Reinicie o QGIS.
  6. Abra o dock/toolbar do QGIS MCP e clique em Start Server. Deve mostrar algo como porta 9876 ativa.

Esse passo é idêntico em Linux, macOS e Windows — o plugin em si é Python puro (PyQGIS), sem dependência de sistema operacional.

Etapa 2 — Instalar o uv/uvx

Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Isso instala o binário normalmente em ~/.local/bin/uv e ~/.local/bin/uvx. Confirme com:

ls -la ~/.local/bin/uvx

macOS

curl -LsSf https://astral.sh/uv/install.sh | sh

ou, se preferir usar o Homebrew:

brew install uv

Windows

Abra o PowerShell ou o Prompt de Comando e rode:

pip install uv

Depois confirme onde ficou instalado:

where uvx

Exemplo de resultado: C:\Users\SEU_USUARIO\.local\bin\uvx.exe. Guarde esse caminho — ele será necessário na Etapa 3.

Etapa 3 — Configurar o Claude Desktop

Vá em Claude Desktop → Settings → Developer → Edit Config. Isso abre o arquivo claude_desktop_config.json.

Localização do arquivo por sistema:

Sistema Caminho
Linux ~/.config/Claude/claude_desktop_config.json
macOS ~/Library/Application Support/Claude/claude_desktop_config.json
Windows %APPDATA%\Claude\claude_desktop_config.json

Adicione a entrada "qgis" dentro de "mcpServers". Se já existirem outros servidores MCP configurados (Zotero, Obsidian, etc.), apenas acrescente "qgis" como mais um item — lembre-se da vírgula entre os itens.

Linux / macOS

{
  "mcpServers": {
    "qgis": {
      "command": "/home/SEU_USUARIO/.local/bin/uvx",
      "args": [
        "--refresh-package",
        "qgis-mcp",
        "--from",
        "git+https://github.com/nkarasiak/qgis-mcp",
        "qgis-mcp-server"
      ]
    }
  }
}

No macOS, o caminho normalmente é /Users/SEU_USUARIO/.local/bin/uvx.

Windows

{
  "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"
      }
    }
  }
}

Por que caminho completo e não só "uvx"? Aplicativos de interface gráfica (GUI) — no Windows, macOS ou Linux — frequentemente não herdam o PATH do seu terminal/shell. Se você colocar só "uvx" sem o caminho completo, o Claude Desktop pode não encontrar o executável mesmo que ele funcione perfeitamente no terminal. Usar o caminho absoluto elimina essa ambiguidade.

Validando o JSON antes de reiniciar

Depois de editar, sempre valide a sintaxe antes de reiniciar o Claude Desktop — um erro de vírgula faz a configuração inteira falhar silenciosamente:

python3 -m json.tool ~/.config/Claude/claude_desktop_config.json

(ajuste o caminho para macOS/Windows conforme a tabela acima). Se o comando devolver o JSON formatado sem erro, está tudo certo. Se apontar erro de sintaxe (ex.: "Expecting ',' delimiter"), corrija a linha indicada antes de prosseguir.

Etapa 4 — Reiniciar tudo

  1. Confirme que o QGIS está aberto e o servidor do plugin QGIS MCP está rodando (Start Server já clicado).
  2. Feche o Claude Desktop completamente — não só a janela. No Linux, confirme que não sobrou processo: bash pgrep -fl claude-desktop No Windows/macOS, feche também pelo ícone da bandeja/menu de status, se houver.
  3. Abra o Claude Desktop novamente.

Etapa 5 — Verificar a conexão

Em Settings → Developer, na seção "Servidores MCP locais" (ou "Local MCP servers"), o servidor qgis deve aparecer com status running, ao lado de outros servidores que você tenha configurado.

Depois, numa conversa nova, teste com:

Faça ping no QGIS e me diga a versão instalada.

Se estiver tudo certo, o Claude vai responder confirmando o "pong" do plugin e a versão do QGIS.

Diagnóstico de problemas comuns

Sintoma Causa provável Solução
Servidor qgis não aparece na lista de MCP servers A entrada não foi salva no arquivo certo, ou o JSON ficou inválido Confira o caminho do arquivo (tabela da Etapa 3) e valide com python3 -m json.tool
Erro "Could not attach to MCP server qgis" uv/uvx não instalado, caminho errado, ou plugin do QGIS não está com o servidor rodando Confirme uvx no caminho configurado; confirme que clicou em "Start Server" dentro do QGIS
JSON inválido após editar manualmente Faltou vírgula entre entradas de mcpServers, ou sobrou vírgula no último item Rode python3 -m json.tool (Linux/Mac) para localizar a linha do erro exato
Servidor aparece "running" mas Claude não consegue falar com o QGIS Plugin dentro do QGIS não está com "Start Server" ativo, ou QGIS foi fechado depois Reabra o QGIS e clique em Start Server antes de testar de novo
Plugin (dentro do QGIS) e servidor MCP (fora do QGIS) ficam fora de sincronia após atualização Um lado foi atualizado e o outro não Use o comando diagnose (uma das ferramentas do QGIS MCP) para conferir; atualize os dois lados (Plugin Manager do QGIS + reiniciar o Claude Desktop)

Testando o servidor manualmente (fora do Claude)

Se quiser confirmar que o servidor MCP sobe sozinho, sem depender do Claude Desktop, rode no terminal:

Linux/macOS:

~/.local/bin/uvx --from "https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip" qgis-mcp-server

Windows:

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, deve aparecer algo como:

QgisMCPServer starting up
will connect to QGIS at localhost:9876

Referências