Como usar o KwaFlux pelo Claude Code e pelo Claude Desktop (configuração do MCP)

O essencial

• O Claude Code se conecta ao KwaFlux com um único comando claude mcp add, que o próprio KwaFlux gera para você; o Claude Desktop se conecta com uma entrada no claude_desktop_config.json.
• No Claude Code, use o escopo de usuário, para que o KwaFlux fique disponível em todos os projetos, e não só em uma pasta.
• Depois de editar a configuração, feche o Claude Desktop por completo, inclusive pela bandeja do sistema, ou ele não carrega o servidor.
• Os dois clientes pedem confirmação antes de rodar ferramentas MCP, e o /mcp no Claude Code mostra se o KwaFlux se conectou e quantas ferramentas ele oferece.

O Claude consegue comandar o KwaFlux no seu computador pelo servidor MCP local que é instalado junto com o app. Para o Claude Code, o KwaFlux entrega um comando claude mcp add pronto. Para o Claude Desktop, entrega uma entrada JSON para mesclar no claude_desktop_config.json. Em qualquer caso, deixe o KwaFlux aberto enquanto o Claude trabalha.

Neste guia, você vai ver como conectar cada cliente do Claude, onde fica a configuração de cada um, como conferir a conexão, o que pedir primeiro e como resolver os problemas mais comuns.

Conteúdo

1. Claude Code ou Claude Desktop?
2. Antes de começar
3. Claude Code: um comando
4. Claude Code: compartilhar com um projeto
5. Claude Desktop: editar a configuração
6. Os seus primeiros pedidos
7. Trabalhos demorados e timeouts
8. Solução de problemas
9. Perguntas frequentes

Claude Code ou Claude Desktop?

O Claude Code é o agente de programação da Anthropic para o terminal e para IDEs; o Claude Desktop é o app de chat do Claude para Windows e macOS. Os dois rodam servidores MCP locais e os dois podem usar o KwaFlux.

Se a ideia é principalmente conversar com o Claude sobre os seus vídeos, o Claude Desktop é o começo mais simples. Se você já trabalha em um terminal ou em uma IDE, o Claude Code se encaixa ali. Para os outros assistentes, veja a nossa comparação.

Antes de começar

• KwaFlux 1.0.14 ou mais recente, aberto. O servidor MCP conversa com o app em execução.
• Node.js 18 ou mais recente, no PATH. O cartão de Configurações do KwaFlux avisa: “O host inicia o servidor via Node.js 18 ou mais recente, então o Node precisa estar instalado e no PATH.” Se node --version falhar, instale a LTS atual pelo nodejs.org. O cartão de Configurações do KwaFlux também procura o Node.js e grava o caminho completo dele na configuração, como nos exemplos abaixo; se não encontrar o Node.js, ele avisa e grava node no lugar.
• No KwaFlux: abra Configurações › Agent (MCP), escolha Claude em Host MCP e depois Claude Code ou Claude Desktop.

Claude Code: um comando

1. Com Claude Code selecionado, clique em Copiar comando de instalação.
2. Cole em um terminal e execute. Para uma instalação padrão no Windows, o comando é:

claude mcp add --scope user kwaflux -- "C:\Program Files\nodejs\node.exe" "C:\Program Files\KwaFlux\Tools\kwaflux-mcp\kwaflux_mcp.mjs"

3. Abra uma nova sessão do Claude Code e rode /mcp. O kwaflux deve aparecer conectado, com o número de ferramentas.

Duas partes desse comando importam:

• **--scope user** grava o servidor no ~/.claude.json para todos os seus projetos. O padrão do Claude Code, o escopo local, faria o KwaFlux aparecer só na pasta onde você rodou o comando.
• **--** separa as opções do próprio Claude do comando que inicia o servidor. A documentação do Claude Code explica que “tudo o que vem depois de -- é repassado ao servidor sem alterações”.

Claude Code: compartilhar com um projeto

A dica do KwaFlux também oferece um arquivo de projeto: “Adicione ao .mcp.json na raiz do projeto ou execute a CLI.” Um .mcp.json de projeto serve para compartilhar servidores, pelo controle de versão, com todo mundo que trabalha naquela pasta. Use se uma equipe mantém um projeto de vídeo em um repositório e todos têm o KwaFlux instalado no mesmo lugar.

Com Claude Code selecionado, clique em Copiar config e salve como .mcp.json na raiz do projeto:

{
  "mcpServers": {
    "kwaflux": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": [
        "C:\\Program Files\\KwaFlux\\Tools\\kwaflux-mcp\\kwaflux_mcp.mjs"
      ]
    }
  }
}

Em uma sessão interativa, o Claude Code pede aprovação antes de usar servidores do .mcp.json de um projeto. Até você aprovar, o /mcp mostra o servidor como pendente.

Claude Desktop: editar a configuração

1. No KwaFlux, escolha Claude › Claude Desktop e clique em Copiar config.
2. No Claude Desktop, abra Settings (as configurações do app) pelo menu do Claude, vá até Developer (desenvolvedor) e clique em Edit Config (editar configuração). Isso abre, ou cria, o arquivo: - Windows: %APPDATA%\Claude\claude_desktop_config.json - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
3. Mescle a entrada kwaflux dentro de mcpServers. Não apague os servidores que já estão lá.
4. Feche o Claude Desktop por completo, inclusive o ícone na bandeja do sistema ou na barra de menus, e abra de novo. A dica do KwaFlux é direta nesse ponto: “Feche o Claude Desktop por completo após editar.”
5. Em uma conversa, abra o menu no canto inferior esquerdo da caixa de texto, vá até Connectors (conectores) e confira se o kwaflux aparece com as ferramentas dele.

O Claude Desktop pede a sua aprovação antes de cada ferramenta rodar, a menos que você libere uma ferramenta para a conversa.

Os seus primeiros pedidos

Comece com uma verificação somente leitura:

Use as ferramentas do KwaFlux para conferir se o KwaFlux está rodando e se eu fiz login.

Depois experimente trabalhos de verdade, com caminhos locais completos:

A interpolação de quadros e as ferramentas de recorte e substituição ficam no app; o assistente é instruído a mandar você para lá nesses casos. Os downloads por agentes continuam desativados a menos que você mude Permitir que agentes iniciem downloads, em Autorização de agentes, para o modo que pede confirmação a cada download. Aí o KwaFlux mostra um pop-up para cada download, e o assistente também pede que você confirme no chat que tem o direito de baixar aquele conteúdo.

Dica: no Claude Code, as ferramentas do KwaFlux aparecem como mcp__kwaflux__<tool>, por exemplo mcp__kwaflux__kwaflux_get_app_status. Use esses nomes para liberar as ferramentas somente leitura nas suas regras de permissão, assim o Claude não pede confirmação toda vez que consulta a lista de tarefas.

Trabalhos demorados e timeouts

Trabalhos de vídeo podem levar minutos. A ferramenta de espera do KwaFlux aguarda até 300 segundos por chamada, 60 por padrão, e então informa se a tarefa terminou. Se não terminou, o Claude pode simplesmente esperar de novo.

Se uma máquina lenta fizer o próprio servidor demorar para iniciar, a documentação do Claude Code descreve a variável de ambiente MCP_TIMEOUT para a inicialização, por exemplo MCP_TIMEOUT=10000 claude. Para chamadas de ferramenta, uma entrada do .mcp.json de projeto aceita um campo timeout em milissegundos. Use um valor acima de 300.000 se você pedir esperas longas.

Solução de problemas

Para problemas comuns a todos os hosts, veja o guia de solução de problemas do MCP do KwaFlux.

Conclusão

No Claude Code, rode o comando que o KwaFlux copia para você, com escopo de usuário, e confira o /mcp. No Claude Desktop, mescle a entrada no claude_desktop_config.json e feche o app por completo antes de abrir de novo. Depois, deixe o KwaFlux aberto e comece com uma verificação de status.

Comande o KwaFlux pelo Claude

O KwaFlux inclui um servidor MCP local para Claude Code, Claude Desktop e outros apps MCP. O processamento de IA roda na sua própria GPU e os seus arquivos de mídia não são enviados para processamento. Roda no Windows 10 (64 bits, versão 1809 ou mais recente), no Windows 11 e no macOS 12 ou mais recente em Apple Silicon. Importar arquivos e explorar o app não exigem conta. O login com um plano pago só é necessário para exportar, converter, reparar um arquivo ou baixar um arquivo de um link.

Baixar o KwaFlux · Ver planos