Configuração MCP do Claude Desktop: local do arquivo, exemplo em JSON e setup

Você editou o JSON, reiniciou o app e nada aconteceu. Nenhum ícone de martelo, nenhuma ferramenta nova, nenhuma mensagem de erro. Essa falha silenciosa é o caso mais comum com uma configuração MCP do Claude Desktop, e quase sempre se resume a uma de três causas: você editou o arquivo errado, o JSON tem um pequeno erro de sintaxe ou o app nunca foi reiniciado por completo. Este artigo percorre as três, na ordem em que você vai encontrá-las.

Você vai ver a localização exata do claude_desktop_config.json no Windows e no macOS (incluindo a armadilha do MSIX no Windows, que manda suas edições para um arquivo que ninguém lê), um exemplo de JSON que funciona e que você pode colar hoje, uma forma de confirmar que um servidor realmente se conectou e uma rotina curta de solução de problemas baseada nos logs MCP. Perto do final há um tutorial de como usar o Claude Sonnet 5 no PicassoIA para depurar a sua própria configuração, além de uma olhada em como conectar geradores de imagem e vídeo quando a base já estiver funcionando.

💡 Versão curta: o arquivo fica em claude_desktop_config.json, precisa de um objeto mcpServers no nível superior, todos os caminhos dentro dele devem ser absolutos, e o app precisa ser totalmente fechado e aberto de novo após cada edição.

Onde fica o arquivo de configuração

O Claude Desktop lê um arquivo JSON na inicialização para descobrir quais servidores MCP (servidores do Model Context Protocol) deve iniciar. O arquivo não existe até que você o abra pela tela de configurações ou o crie manualmente, então uma instalação nova não tem nada para encontrar. Sua localização depende do sistema operacional e, no Windows, de como você instalou o app.

Caminho no Windows e a armadilha do MSIX

Em uma instalação padrão do Windows, o arquivo fica aqui:

%APPDATA%\Claude\claude_desktop_config.json

Copiar prompt

Expandido, isso é C:\Users\<your name>\AppData\Roaming\Claude\claude_desktop_config.json. Pressione Win+R, cole a primeira forma e pressione Enter para abrir a pasta certa.

Aqui está a armadilha. Quando o Claude Desktop é instalado como pacote MSIX (a Microsoft Store e algumas instalações via WinGet funcionam assim), o Windows virtualiza a pasta AppData desse app. Vários relatos públicos de bugs descrevem o mesmo resultado: o botão Edit Config abre o arquivo comum %APPDATA%, enquanto o próprio app lê uma cópia escondida dentro da pasta do pacote:

%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json

Copiar prompt

Se você editar o primeiro arquivo, seus servidores são ignorados sem nenhum aviso. Uma verificação rápida no PowerShell mostra em qual situação você está:

Test-Path "$env:LOCALAPPDATA\Packages\Claude_pzs8sxrjxfjjc"

Copiar prompt

Se isso imprimir True, coloque seu bloco mcpServers no caminho do pacote, reinicie e veja se o servidor aparece. Os nomes das pastas de pacote podem mudar entre versões, então trate o caminho acima como ponto de partida. Se ele não corresponder, procure dentro de %LOCALAPPDATA%\Packages uma pasta que comece com Claude_.

Caminho no macOS e observações sobre Linux

No Mac, o arquivo fica dentro da pasta Library, que o Finder esconde por padrão:

~/Library/Application Support/Claude/claude_desktop_config.json

Copiar prompt

No Finder, escolha Ir, depois Ir para a pasta, e cole ~/Library/Application Support/Claude. No Terminal, open ~/Library/Application\ Support/Claude faz o mesmo trabalho.

Não existe uma versão oficial do Claude Desktop para Linux. Versões da comunidade costumam seguir a convenção XDG e ler ~/.config/Claude/claude_desktop_config.json, mas confira as notas da versão que você usa antes de confiar nesse caminho.

Abra pelas configurações

A rota menos sujeita a erros é pelo próprio app:

1. Clique no menu Claude na barra de menus do sistema (não nas configurações dentro da janela do chat).
2. Escolha Settings (Configurações).
3. Abra a aba Developer (Desenvolvedor) na barra lateral esquerda.
4. Clique em Edit Config.

Isso cria o arquivo quando ele não existe e o mostra no seu gerenciador de arquivos. Em uma instalação MSIX no Windows, compare a pasta que ele abre com o caminho do pacote indicado acima antes de confiar nela.

Aqui estão todos os locais reunidos em um só lugar:

Como é o JSON

Como funciona o objeto mcpServers

O arquivo inteiro é um único objeto JSON. O Claude Desktop procura uma propriedade de nível superior chamada mcpServers. Dentro dela, cada propriedade é um servidor, e o nome da propriedade é o rótulo que você vê no app. Cada entrada é uma pequena receita para iniciar um programa no seu computador, e o Claude se comunica com esse programa pela entrada e saída padrão.

O command certo depende de como o servidor foi escrito. Servidores Node.js publicados no npm começam com npx. Servidores que você mesmo criou ou clonou começam com node seguido do caminho para o arquivo compilado. Servidores Python geralmente são iniciados pelo uvx, que exige a ferramenta uv instalada. Em todos os casos, a regra é a mesma: o que você digitar como command precisa funcionar quando digitado em um terminal, porque é exatamente isso que o Claude Desktop faz por você.

Se o Claude Desktop já adicionou outras entradas de nível superior ao arquivo (versões mais novas podem guardar algumas preferências ali), deixe-as como estão e adicione mcpServers ao lado delas. Substituir o arquivo inteiro por um trecho colado é como as pessoas perdem essas configurações.

Exemplos para macOS e Windows

Aqui está o servidor oficial de sistema de arquivos em um Mac. Troque username pelo nome real da sua conta:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/Users/username/Downloads"
      ]
    }
  }
}

Copiar prompt

A versão para Windows é idêntica, exceto pelos caminhos, e cada barra invertida precisa ser duplicada, porque uma barra invertida única é um caractere de escape no JSON:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:\\Users\\username\\Desktop",
        "C:\\Users\\username\\Downloads"
      ]
    }
  }
}

Copiar prompt

Três detalhes fazem a maior parte do trabalho aqui. A flag -y faz com que npx instale o pacote do servidor sem fazer uma pergunta que ninguém estará ali para responder. As pastas depois do nome do pacote são os únicos lugares que o servidor pode tocar. E todos esses caminhos são absolutos, porque caminhos relativos são um motivo clássico para um servidor nunca iniciar.

Você também precisa do Node.js, já que o npx vem com ele. Rode node --version em um terminal; se aparecer um número de versão, está tudo certo, e a versão LTS é a escolha segura.

💡 Dica: escolha o rótulo em mcpServers pensando em pessoas, não na máquina. filesystem, notes ou weather servem bem, e o nome só aparece nos menus e no nome do arquivo de log.

Adicione servidores e segredos com segurança

Variáveis de ambiente para segredos

Servidores reais muitas vezes precisam de uma credencial. Coloque-a no objeto env desse servidor, nunca em args, onde ela apareceria nas listas de processos. Este exemplo roda dois servidores lado a lado:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Documents/notes"
      ]
    },
    "weather": {
      "command": "node",
      "args": ["/Users/username/tools/weather-server/build/index.js"],
      "env": {
        "WEATHER_API_TOKEN": "paste-your-token-here"
      }
    }
  }
}

Copiar prompt

Repare na vírgula entre os dois blocos de servidor e na ausência de vírgula depois do último. Esses dois detalhes causam mais arquivos quebrados do que qualquer outra coisa.

O arquivo de configuração é texto simples, então trate-o como um arquivo de senhas. Não o envie para um repositório público, não o cole em um chat ou em uma captura de tela com o token visível, e mantenha o acesso às pastas restrito. Um servidor roda com as permissões da sua conta de usuário, o que significa que ele pode fazer tudo o que você faria manualmente. Aponte o servidor de sistema de arquivos para uma pasta de projeto, não para o seu diretório pessoal inteiro.

Servidores remotos usam conectores

O arquivo JSON inicia processos locais. Um servidor MCP remoto e hospedado é outra coisa: ele já roda em outro lugar e você o acessa por URL. O Claude Desktop espera que eles sejam adicionados em Settings, depois em Connectors (Conectores), e não como entradas em claude_desktop_config.json. Colar uma URL em command é uma das formas mais discretas de acabar com um servidor que nunca carrega.

Reinicie e confirme que funciona

Feche por completo e depois reabra

O Claude Desktop lê a configuração uma vez, na inicialização. Salvar o arquivo não faz nada por si só. Fechar a janela também não basta, porque o app pode continuar rodando em segundo plano. No macOS, pressione Cmd+Q ou use Claude e depois Quit (Sair). No Windows, feche pelo ícone na bandeja do sistema se o app ficar ali. Depois, abra de novo.

Trabalhe em pequenos passos. Adicione um servidor, reinicie, confirme e só então adicione o próximo. Quando você cola cinco servidores de uma vez e o arquivo se recusa a carregar, não há como saber qual bloco o quebrou.

Confira o menu de conectores

Quando o app voltar, olhe o campo de mensagem do chat e clique no botão Add files, connectors, and more (Adicionar arquivos, conectores e mais). Passe o cursor sobre Connectors, clique em Manage connectors (Gerenciar conectores) e escolha seu servidor na lista. Um servidor funcionando mostra as ferramentas que oferece. O servidor de sistema de arquivos, por exemplo, lista ferramentas para ler arquivos, gravar arquivos, movê-los e buscá-los.

Depois, faça um teste real com um prompt como "Liste os arquivos da minha pasta Downloads." O Claude pede permissão antes de chamar uma ferramenta. Aprove a chamada, e a resposta deve trazer nomes reais de arquivos. Se ele responder que não tem acesso aos seus arquivos, o servidor não se conectou.

Corrija os erros que impedem o carregamento

Sintaxe JSON quebrada

Um único caractere fora do lugar impede o arquivo inteiro de carregar. Estes são os suspeitos habituais:

• Uma vírgula sobrando depois da última propriedade ou item de array.
• Um comentário. O JSON não tem comentários, então linhas com // são erros.
• Aspas curvas coladas de uma página web ou de um editor de texto, em vez das aspas retas comuns.
• Uma barra invertida única em um caminho do Windows.
• Uma chave ou colchete que falta depois que você apagou um bloco de servidor.

Este trecho junta três deles em poucas linhas. Consegue identificá-los?

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\Users\username\Desktop",],
    }
  }
}

Copiar prompt

O caminho usa barras invertidas simples, o array termina com uma vírgula antes do colchete de fechamento, e a linha args termina com uma vírgula antes da chave de fechamento. Corrija as três e o arquivo passa na análise.

Antes de reiniciar, valide o arquivo. Qualquer validador de JSON funciona, ou você pode usar o Node.js, que você já tem:

node -e "JSON.parse(require('fs').readFileSync(process.argv[1],'utf8')); console.log('valid')" claude_desktop_config.json

Copiar prompt

Se ele imprimir valid, a sintaxe está certa e o problema está em outro lugar.

Problemas de comando não encontrado

Quando o JSON é válido, mas o servidor ainda falha, o culpado geralmente é o command. Um app de desktop não lê o perfil do seu shell, então um Node.js instalado por um gerenciador de versões pode ser invisível para ele. Rode which npx em um terminal e coloque o caminho completo no campo command, em vez de npx.

Primeiro, rode o comando exato manualmente para ver se ele funciona fora do app:

npx -y @modelcontextprotocol/server-filesystem /Users/username/Desktop

Copiar prompt

No Windows, se o log mencionar um erro sobre ${APPDATA} dentro de um caminho, adicione o valor expandido de %APPDATA% ao bloco env desse servidor, por exemplo "APPDATA": "C:\\Users\\username\\AppData\\Roaming\\". Verifique também se %APPDATA%\npm existe. Se não existir, instale o npm globalmente com npm install -g npm e depois reinicie o app.

Leia os logs MCP

Os logs mostram o que o app viu. Abra a pasta de logs da tabela acima e procure dois tipos de arquivo. mcp.log guarda mensagens gerais sobre conexões e falhas. Arquivos com nomes mcp-server-NAME.log guardam a saída stderr de cada servidor, que muitas vezes é onde está a mensagem de erro real. No Mac, você pode acompanhá-los ao vivo:

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

Copiar prompt

No Windows, o PowerShell faz o mesmo trabalho:

Get-Content "$env:APPDATA\Claude\logs\mcp.log" -Tail 40 -Wait

Copiar prompt

Um log que não muda depois de um reinício já é uma pista: o app provavelmente está lendo um arquivo de configuração diferente daquele que você editou, o que leva de volta ao caminho do MSIX.

Como usar o Sonnet 5 no PicassoIA

Um segundo par de olhos é a forma mais rápida de achar uma vírgula perdida. O Claude Sonnet 5 no PicassoIA é um modelo de texto que lê JSON colado, rastreamentos de pilha (stack traces) e até capturas de tela de um erro, então funciona bem como revisor de configuração.

Abra a página do modelo

Vá até a página do Claude Sonnet 5 na coleção de Large Language Models e abra a caixa de prompt. Mantenha uma aba do navegador para o modelo e outra para o seu editor, para colar o conteúdo de um lado para o outro.

Defina o esforço e o tamanho da saída

O modelo expõe algumas configurações, e algumas delas importam aqui:

• effort: vem por padrão em low, o que desliga o pensamento para a resposta mais rápida. Isso basta para uma checagem de sintaxe. Mude para medium ou high quando precisar que ele raciocine sobre caminhos em vários servidores.
• max_tokens: o padrão de 8.192 é mais que suficiente para um arquivo completo corrigido.
• system_prompt: defina uma vez, por exemplo "Você revisa arquivos claude_desktop_config.json. Aponte a linha exata que está errada e depois devolva o arquivo corrigido."
• image: anexe uma captura de tela do erro. Aumente o max_image_resolution acima do padrão de 0,5 megapixel se o texto do log estiver pequeno.

Para checagens rápidas de sim ou não, o Claude 4.5 Haiku responde mais rápido. Para um quebra-cabeça teimoso envolvendo vários arquivos, o Claude Opus 4.7 é a opção mais pesada.

Cole a configuração e pergunte

Antes, substitua cada token por um marcador de posição. Depois cole o arquivo e faça uma pergunta específica:

This claude_desktop_config.json is on Windows. The filesystem server never
appears in Claude Desktop. Check the JSON syntax, check the path escaping,
and tell me which line to fix first.

Copiar prompt

Compare a resposta com o seu arquivo linha por linha, em vez de colar de volta sem olhar, e rode no resultado o validador do Node.js mencionado antes.

Conecte ferramentas de imagem e vídeo

Quando a base estiver funcionando, começa a parte interessante: dar ao Claude ferramentas que criam coisas. O PicassoIA oferece uma API para desenvolvedores e uma conexão MCP, ambas limitadas a quatro modelos no momento em que este texto foi escrito:

As conexões MCP do PicassoIA são criadas na página da sua conta em picassoia.com depois que você faz login. Elas são hospedadas, então vale a rota de conectores vista antes: adicione-as em Settings, depois em Connectors, e não como uma entrada mcpServers. Os trabalhos rodam de forma assíncrona. Uma solicitação inicia uma predição, e o resultado é buscado quando ela termina. Cada conta pode rodar 5 predições ao mesmo tempo, e esse limite é compartilhado por todas as conexões MCP que você faz, então um pedido em lote feito pelo Claude pode ficar na fila atrás de si mesmo.

💡 Dica: peça uma imagem primeiro, confira o resultado e só depois aumente a escala. Um único prompt de foto em 16:9 mostra mais rápido do que um lote de dez imagens se a conexão e as permissões estão certas.

Um bom primeiro pedido é concreto: "Crie uma foto em 16:9 de uma caneca de cerâmica sobre uma mesa de carvalho, com luz suave da manhã, usando o PicassoIA Image." O Claude escolhe a ferramenta, espera o trabalho terminar e entrega o link. Se ele pedir permissão a cada vez, é a mesma etapa de aprovação que você viu com o servidor de sistema de arquivos, e está funcionando como deveria.

Faça suas próximas imagens

Seu arquivo de configuração agora faz o que deveria: aponta para o lugar certo, passa na análise limpa, inicia seus servidores e registra o que dá errado. Essa é a metade chata de trabalhar com ferramentas de IA, e você só precisa fazê-la uma vez.

A metade divertida é a criação. Abra o PicassoIA Image e escreva um prompt sobre algo que você preza, uma rua que você conhece ou um produto que você vende. Refaça-o com o PicassoIA Image Editor Pro e depois anime o melhor resultado com o PicassoIA Video. Explore todos os modelos em picassoia.com/en/all-models, escolha um que você ainda não testou e crie sua primeira imagem hoje.