Claude Desktop MCP

Um servidor MCP para integração com o aplicativo Claude Desktop no macOS. Requer que o aplicativo Claude Desktop esteja instalado e configurado.

GitHub
1
Experimente este MCPPatrocinado

Documentação

MCP Claude Desktop

Um servidor Model Context Protocol (MCP) que permite ao Claude Code se comunicar com o Claude Desktop. Este servidor permite que o Claude Code envie prompts para o Claude Desktop e consulte as respostas.

Inspirado por claude-chatgpt-mcp, este projeto adapta o conceito para o ecossistema da Apple usando automação nativa do macOS.

Recursos

  • Enviar prompts do Claude Code para o Claude Desktop
  • Consulta automática de respostas com timeout configurável
  • Listar conversas disponíveis no Claude Desktop
  • Tratamento de erros e lógica de tentativas
  • Log abrangente

Instalação

Você pode instalar e usar este servidor MCP de duas maneiras:

Opção 1: Usando npx (Recomendado)

A maneira mais simples de usar este servidor é diretamente com npx, sem qualquer instalação:

{
  "mcpServers": {
    "claude-desktop": {
      "command": "npx",
      "args": ["mcp-claude-desktop"]
    }
  }
}

Opção 2: Instalação Local

  1. Clone este repositório:
git clone https://github.com/dpaluy/mcp-claude-desktop
cd mcp-claude-desktop
  1. Instale as dependências:
npm install
  1. Compile o projeto:
npm run build
  1. Configure o MCP:
{
  "mcpServers": {
    "claude-desktop": {
      "command": "node",
      "args": ["/path/to/mcp-claude-desktop/dist/index.js"]
    }
  }
}

Requisitos do Sistema

  • macOS 11.0+ (Big Sur ou posterior)
  • Node.js 18+
  • Aplicativo Claude Desktop instalado
  • Permissões de acessibilidade concedidas para AppleScript

Concedendo Permissões de Acessibilidade

  1. Abra Preferências do Sistema > Segurança e Privacidade > Privacidade
  2. Selecione "Acessibilidade" na barra lateral esquerda
  3. Clique no cadeado para fazer alterações
  4. Adicione o Terminal (ou seu aplicativo de terminal) aos aplicativos permitidos
  5. Reinicie seu terminal

Ferramentas MCP

Este servidor MCP fornece duas ferramentas:

ask

  • Finalidade: Enviar um prompt para o Claude Desktop e obter uma resposta
  • Parâmetros:
    • prompt: O texto a ser enviado para o Claude Desktop (obrigatório)
    • conversationId: ID opcional para continuar uma conversa específica
    • timeout: Timeout de resposta em segundos (opcional, padrão: 30, máximo: 300)
    • pollingInterval: Com que frequência verificar a resposta em segundos (opcional, padrão: 1,5, mínimo: 0,5)

get_conversations

  • Finalidade: Obter uma lista de conversas disponíveis no Claude Desktop
  • Parâmetros: Nenhum

Uso

Uma vez configurado, o Claude Code pode usar o MCP de várias maneiras:

Uso de Propósito Geral

Quando o Claude usa essas ferramentas, ele as chamará com parâmetros como:

Uso básico:

  • Ferramenta: ask
  • Parâmetros: { "prompt": "What is dependency injection?" }

Com timeout personalizado:

  • Ferramenta: ask
  • Parâmetros: { "prompt": "Explain quantum computing", "timeout": 120 }

Com timeout e intervalo de consulta:

  • Ferramenta: ask
  • Parâmetros: { "prompt": "Quick question", "timeout": 10, "pollingInterval": 0.5 }

Obter conversas:

  • Ferramenta: get_conversations
  • Parâmetros: {}

Como Usar no Claude

Uma vez que o servidor MCP esteja configurado e em execução, você pode usar essas ferramentas diretamente no Claude:

Uso básico:

  • "Use a ferramenta ask para perguntar ao Claude Desktop: Quais são as melhores práticas para tratamento de erros em Python?"
  • "Use get_conversations para listar todas as minhas conversas do Claude Desktop"

Com timeout personalizado:

  • "Use a ferramenta ask com timeout 60 para perguntar ao Claude Desktop: Explique a implementação da árvore B+"
  • "Use ask com timeout 10 e pollingInterval 0.5 para perguntar ao Claude Desktop: Quanto é 2+2?"

Importante: A configuração do servidor MCP (mostrada acima) apenas informa ao Claude como iniciar o servidor. Os parâmetros timeout e pollingInterval são especificados quando você usa a ferramenta no Claude, não no arquivo de configuração do servidor.

Limitações Conhecidas

Leitura de Respostas

Devido à arquitetura baseada em Electron do Claude Desktop, esta integração MCP não pode ler as respostas do Claude programaticamente. A ferramenta pode com sucesso:

  • ✅ Enviar prompts para o Claude Desktop
  • ✅ Criar novas conversas
  • ✅ Ativar e focar a janela do Claude
  • ❌ Ler as respostas do Claude

Esta é uma limitação de como os aplicativos Electron expõem elementos de interface através de APIs de acessibilidade. Quando você usa a ferramenta ask, receberá uma confirmação de que a mensagem foi enviada, mas precisará verificar a janela do Claude Desktop diretamente para ver a resposta.

Soluções Alternativas

  1. Use a API do Claude: Para acesso programático às respostas, considere usar a API do Claude diretamente em vez da automação de desktop
  2. Verificação manual: Após enviar um prompt, verifique manualmente a janela do Claude Desktop para a resposta
  3. Automação unidirecional: Use esta ferramenta para cenários onde você só precisa enviar prompts sem ler respostas

Integração com Comandos do Claude

Os Comandos do Claude permitem criar fluxos de trabalho reutilizáveis que combinam ferramentas MCP. Este projeto funciona perfeitamente com os Comandos do Claude para permitir automação poderosa.

Exemplo: Comando de Revisão de Código por Pares

Incluímos um exemplo de Comando do Claude que demonstra como usar o MCP Claude Desktop para revisões de código automatizadas. O comando usa git para analisar alterações recentes e as envia para o Claude Desktop para feedback de revisão por pares.

Configuração

  1. Copie o comando de exemplo para o diretório de Comandos do Claude:

    cp examples/claude-peer-review.md ~/.claude/commands/

  2. O comando estará disponível no Claude Code como /claude-peer-review

Uso

O comando de revisão por pares aceita até 3 argumentos:

  • description: Quais alterações revisar (ex.: "correção de autenticação")
  • polling_interval: Com que frequência verificar a resposta (padrão: 1,5s)
  • timeout: Tempo máximo de espera pela resposta (padrão: 30s)

Exemplos:

# Review most recent commit with defaults
/claude-peer-review

# Review with description
/claude-peer-review "bug fix for user login"

# Custom polling interval (2 seconds)
/claude-peer-review "API update" 2

# Custom timeout for complex reviews (2 minutes)
/claude-peer-review "major refactor" 1.5 120

Como Funciona

  1. Integração com Git: O comando busca automaticamente:

    • Status atual do git
    • Estatísticas de commits recentes
    • Diff completo das alterações
    • Nome da branch atual

  2. Revisão pelo Claude Desktop: Envia as alterações para o Claude Desktop com perguntas de revisão específicas:

    • Adequação do código e qualidade da implementação
    • Preocupações de segurança ou possíveis bugs
    • Qualidade do código e melhores práticas
    • Sugestões de melhorias

  3. Tratamento de Respostas: Usa o mecanismo de consulta do servidor MCP para aguardar a resposta do Claude

  4. Geração de Resumo: Fornece um resumo estruturado de:

    • Alterações revisadas
    • Feedback do Claude
    • Ações tomadas com base no feedback
    • Status final da revisão

Criando Seus Próprios Comandos

Você pode criar Comandos do Claude personalizados que aproveitam o MCP Claude Desktop. Os comandos devem:

  1. Incluir as ferramentas no frontmatter:

    ---
allowed-tools: mcp__claude-desktop__ask, mcp__claude-desktop__get_conversations
---

  2. Usar as ferramentas MCP com parâmetros apropriados:

    mcp__claude-desktop__ask
prompt: "Your prompt here"
timeout: 60
pollingInterval: 2

  3. Tratar timeouts com elegância e sugerir timeouts mais longos para consultas complexas

Veja o comando de exemplo para uma implementação completa.

Desenvolvimento

Executando em Modo de Desenvolvimento

npm run dev

Executando Testes

npm test

Lint

npm run lint

Verificação de Tipos

npm run typecheck

API

Ferramentas

ask

Envie um prompt para o Claude Desktop e obtenha uma resposta.

Parâmetros:

  • prompt (string, obrigatório): O prompt a ser enviado
  • conversationId (string, opcional): Continuar uma conversa específica
  • timeout (número, opcional): Timeout de resposta em segundos
    • Padrão: 30 segundos
    • Mínimo: 1 segundo
    • Máximo: 300 segundos (5 minutos)
  • pollingInterval (número, opcional): Com que frequência verificar a resposta em segundos
    • Padrão: 1,5 segundos
    • Mínimo: 0,5 segundos
    • Máximo: 10 segundos

Resposta:

String containing Claude's response

get_conversations

Obtenha uma lista de conversas disponíveis no Claude Desktop.

Parâmetros: Nenhum

Resposta:

{
  conversations: string[];
  timestamp: string;
}

Arquitetura

O servidor MCP usa AppleScript para se comunicar com o Claude Desktop:

  1. O Claude Code envia um prompt via MCP
  2. O AppleScript ativa o Claude Desktop e cria uma nova conversa
  3. O prompt é digitado no Claude Desktop
  4. O servidor consulta o Claude Desktop pela resposta
  5. Quando uma resposta é detectada, ela é analisada e retornada ao Claude Code

Solução de Problemas

Problemas Comuns

  1. "Falha na execução do AppleScript"

    • Certifique-se de que o Claude Desktop está instalado e em execução
    • Verifique as permissões de acessibilidade
    • Tente executar o servidor com nível de log mais alto: LOG_LEVEL=3

  2. "Resposta expirou"

    • Aumente o parâmetro de timeout: timeout: 60 (60 segundos)
    • Para consultas complexas, use timeouts mais longos: timeout: 120 (2 minutos)
    • Reduza o intervalo de consulta para detecção mais rápida: pollingInterval: 0.5
    • Verifique se o Claude Desktop está respondendo normalmente
    • Certifique-se de que o sistema não está sob carga pesada

  3. "Permissão negada"

    • Conceda permissões de acessibilidade ao seu terminal
    • Execute o comando de compilação com as permissões adequadas

  4. O Servidor MCP Falha Após Enviar Solicitações Se o servidor MCP falhar após lidar com solicitações, você pode:

    • Desativar a consulta de respostas (recomendado para estabilidade):

      export SKIP_CLAUDE_POLLING=true

      Isso enviará a mensagem para o Claude Desktop, mas não tentará ler a resposta.

    • Ativar log de depuração para ver o que está acontecendo:

      export LOG_LEVEL=3

    • Verificar a saída stderr - Todos os logs agora são gravados em stderr para evitar interferência com o protocolo MCP no stdout.

Limitações Conhecidas com a Consulta de Respostas

A consulta de respostas pode ocasionalmente causar instabilidade devido a:

  • Duração estendida da consulta (padrão de 30 segundos)
  • Leitura complexa de elementos de interface de aplicativos Electron
  • Problemas de temporização com a geração de respostas do Claude

Considere usar SKIP_CLAUDE_POLLING=true para operação mais confiável se você não precisar da leitura de respostas.

Contribuindo

Aceitamos contribuições para o MCP Claude Desktop! Seja corrigindo bugs, adicionando recursos ou melhorando a documentação, sua ajuda é apreciada.

Começando

  1. Faça um fork do repositório
  2. Clone seu fork: 
    git clone https://github.com/YOUR_USERNAME/mcp-claude-desktop
cd mcp-claude-desktop
  3. Instale as dependências: 
    npm install
  4. Crie uma nova branch: 
    git checkout -b feature/your-feature-name

Fluxo de Trabalho de Desenvolvimento

  1. Faça suas alterações
  2. Execute os testes para garantir que tudo funciona: 
    npm test
  3. Execute o lint para manter a qualidade do código: 
    npm run lint
  4. Execute a verificação de tipos: 
    npm run typecheck
  5. Compile o projeto: 
    npm run build

Diretrizes de Estilo de Código

  • Use TypeScript para todo o código-fonte
  • Siga o estilo de código existente (aplicado pelo ESLint)
  • Escreva mensagens de commit significativas
  • Adicione testes para novos recursos
  • Atualize a documentação conforme necessário

Enviando Alterações

  1. Faça commit das suas alterações com uma mensagem descritiva: 
    git commit -m "feat: add support for conversation history"
  2. Envie para seu fork: 
    git push origin feature/your-feature-name
  3. Crie um Pull Request no GitHub

Diretrizes para Pull Requests

  • Forneça uma descrição clara das alterações
  • Referencie quaisquer problemas relacionados
  • Certifique-se de que todos os testes passam
  • Atualize o README se estiver adicionando novos recursos
  • Seja responsivo ao feedback da revisão de código

Reportando Problemas

  • Use o GitHub Issues para reportar bugs
  • Inclua a versão do macOS e a versão do Node.js
  • Forneça etapas para reproduzir o problema
  • Inclua mensagens de erro ou logs relevantes

Solicitações de Recursos

  • Abra um issue para discutir novos recursos
  • Explique o caso de uso e os benefícios
  • Esteja aberto a feedback e abordagens alternativas

Licença

MIT