MCP Claude Desktop

Un servidor de Protocolo de Contexto de Modelo (MCP) que permite a Claude Code comunicarse con Claude Desktop. Este servidor permite a Claude Code enviar peticiones a Claude Desktop y sondear las respuestas.

Inspirado en claude-chatgpt-mcp, este proyecto adapta el concepto al ecosistema de Apple utilizando la automatización nativa de macOS.

Características

• Envío de mensajes desde Claude Code a Claude Desktop
• Sondeo automático de respuestas con tiempo de espera configurable
• Lista de conversaciones disponibles en Claude Desktop
• Gestión de errores y lógica de reintento
• Registro exhaustivo

Instalación

Puede instalar y utilizar este servidor MCP de dos maneras:

Opción 1: Utilizando npx (Recomendado)

La forma más sencilla de utilizar este servidor es directamente con npx, sin ninguna instalación:

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

Opción 2: Instalación local

1. Clone este repositorio:

git clone https://github.com/dpaluy/mcp-claude-desktop cd mcp-claude-desktop

2. Instale las dependencias:

npm install

3. Construir el proyecto:

npm run build

4. Configurar MCP:

{ "mcpServers": { "claude-desktop": { "command": "node", "args": ["/path/to/mcp-claude-desktop/dist/index.js"] } }

Requisitos del sistema

• macOS 11.0+ (Big Sur o posterior)
• Node.js 18+
• Aplicación Claude Desktop instalada
• Permisos de accesibilidad concedidos para AppleScript

Concesión de permisos de accesibilidad

1. Abra Preferencias del Sistema > Seguridad y Privacidad > Privacidad
2. Seleccione "Accesibilidad" en la barra lateral izquierda
3. Haga clic en el candado para realizar cambios
4. Añada Terminal (o su aplicación de terminal) a las aplicaciones permitidas
5. Reinicie su terminal

Herramientas MCP

Este servidor MCP proporciona dos herramientas:

preguntar

• Propósito: Enviar un prompt a Claude Desktop y obtener una respuesta
• Parámetros
  • pregunta: El texto a enviar a Claude Desktop (obligatorio)
  • conversationId: ID opcional para continuar una conversación específica
  • tiempo de espera: Tiempo de espera de la respuesta en segundos (opcional, por defecto: 30, máx: 300)
  • pollingInterval: Frecuencia con la que se comprueba la respuesta en segundos (opcional, por defecto: 1,5, mín: 0,5)

obtener_conversaciones

• Propósito: Obtener una lista de conversaciones disponibles en Claude Desktop
• Parámetros: Ninguno

Uso

Una vez configurado, Claude Code puede utilizar el MCP de varias maneras:

Uso General

Cuando Claude utilice estas herramientas, las llamará con parámetros como:

Uso básico:

• Herramienta: ask
• Parámetros: { "prompt": "¿Qué es la inyección de dependencia?" }

Con tiempo de espera personalizado:

• Herramienta: ask
• Parámetros: { "prompt": "Explique la computación cuántica", "timeout": 120 }

Con tiempo de espera e intervalo de sondeo:

• Herramienta: ask
• Parámetros: { "prompt": "Pregunta rápida", "timeout": 10, "pollingInterval": 0.5 }

Obtener conversaciones:

• Herramienta: get_conversations
• Parámetros: {}

Cómo usar en Claude

Una vez que el servidor MCP está configurado y funcionando, puede utilizar estas herramientas directamente en Claude:

Uso básico:

• "Utiliza la herramienta ask para preguntar a Claude Desktop: ¿Cuáles son las mejores prácticas para el manejo de errores en Python?"
• "Usa get_conversations para listar todas mis conversaciones con Claude Desktop"

Con tiempo de espera personalizado:

• "Utilizar la herramienta ask con timeout 60 para preguntar a Claude Desktop: Explicar la implementación del árbol B+"
• "Use ask con timeout 10 y pollingInterval 0.5 para preguntar a Claude Desktop: ¿Qué es 2+2?"

Importante: La configuración del servidor MCP (mostrada arriba) sólo indica a Claude cómo iniciar el servidor. Los parámetros timeout y pollingInterval se especifican cuando se utiliza la herramienta en Claude, no en el archivo de configuración del servidor.

Limitaciones conocidas

Lectura de respuestas

Debido a la arquitectura basada en Electron de Claude Desktop, esta integración MCP no puede leer las respuestas de Claude mediante programación. La herramienta puede con éxito:

• ✅ Enviar avisos a Claude Desktop
• crear nuevas conversaciones
• ✅ Activar y enfocar la ventana de Claude
• ❌ Leer las respuestas de Claude

Se trata de una limitación de cómo las apps de Electron exponen los elementos de la interfaz de usuario a través de las API de accesibilidad. Cuando utilices la herramienta ask, recibirás una confirmación de que se ha enviado el mensaje, pero tendrás que consultar directamente la ventana de Claude Desktop para ver la respuesta.

Soluciones

1. Utilice la API de Claude: Para acceder de forma programática a las respuestas, considere la posibilidad de utilizar directamente la API de Claude en lugar de la automatización del escritorio
2. Verificación manual: Después de enviar una solicitud, compruebe manualmente la respuesta en la ventana de Claude Desktop
3. Automatización unidireccional: Utilice esta herramienta para situaciones en las que sólo necesite enviar avisos sin leer las respuestas

Integración de comandos Claude

Claude Commands le permite crear flujos de trabajo reutilizables que combinan herramientas MCP. Este proyecto funciona perfectamente con Claude Commands para permitir una potente automatización.

Ejemplo: Comando Code Peer Review

Hemos incluido un ejemplo de Comando Claude que demuestra cómo utilizar MCP Claude Desktop para revisiones de código automatizadas. El comando utiliza git para analizar los cambios recientes y los envía a Claude Desktop para la retroalimentación de la revisión por pares.

Configurar

1. Copia el comando de ejemplo a tu directorio de Comandos Claude:

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

2. El comando estará disponible en Claude Code como /claude-peer-review

Uso

El comando peer review acepta hasta 3 argumentos:

• descripción: Qué cambios revisar (por ejemplo, "corrección de autenticación")
• polling_interval: Con qué frecuencia se comprueba si hay respuesta (por defecto: 1,5s)
• timeout: Tiempo máximo de espera para la respuesta (por defecto: 30s)

Ejemplos:

# Revisar el commit más reciente con valores por defecto /claude-peer-review # Revisar con descripción /claude-peer-review "bug fix for user login" # Intervalo de sondeo personalizado (2 segundos) /claude-peer-review "API update" 2 # Tiempo de espera personalizado para revisiones complejas (2 minutos) /claude-peer-review "major refactor" 1.5 120

Cómo funciona

1. Integración con Git: El comando obtiene automáticamente

   • Estado actual de git
   • Estadísticas de commits recientes
   • Diferencia completa de cambios
   • Nombre de la rama actual

2. Revisión deClaude Desktop: Envía los cambios a Claude Desktop con preguntas de revisión específicas:

   • Idoneidad del código y calidad de la implementación
   • Problemas de seguridad o errores potenciales
   • Calidad del código y mejores prácticas
   • Sugerencias de mejora

3. Gestión de respuestas: Utiliza el mecanismo de sondeo del servidor MCP para esperar la respuesta de Claude

4. Generación de resúmenes: Proporciona un resumen estructurado de:

   • Cambios revisados
   • Comentarios de Claude
   • Acciones realizadas en función de los comentarios
   • Estado final de la revisión

Creación de comandos propios

Puedes crear Comandos Claude personalizados que aprovechen el MCP Claude Desktop. Los comandos deben:

1. Incluir las herramientas en el frontmatter:

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

2. Utilizar las herramientas MCP con los parámetros adecuados:

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

3. Manejar los tiempos de espera con elegancia y sugerir tiempos de espera más largos para consultas complejas

Consulte el comando de ejemplo para una implementación completa.

Desarrollo

Ejecutar en modo de desarrollo

npm run dev

Ejecución de pruebas

npm test

Desentrañando

npm run lint

Comprobación de tipos

npm run typecheck

API

Herramientas

preguntar

Envía una pregunta a Claude Desktop y obtiene una respuesta.

Parámetros:

• prompt (cadena, obligatorio): El mensaje a enviar
• conversationId (cadena, opcional): Continuar una conversación específica
• timeout (número, opcional): Tiempo de espera de la respuesta en segundos
  • Predeterminado: 30 segundos
  • Mínimo 1 segundo
  • Máximo: 300 segundos (5 minutos)
• pollingInterval (número, opcional): Frecuencia con la que se comprueba la respuesta en segundos
  • Predeterminado: 1,5 segundos
  • Mínimo: 0.5 segundos
  • Máximo: 10 segundos

Respuesta:

Cadena que contiene la respuesta de Claude

obtener_conversaciones

Obtiene una lista de las conversaciones disponibles en Claude Desktop.

Parámetros: Ninguno

Respuesta:

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

Arquitectura

El servidor MCP utiliza AppleScript para comunicarse con Claude Desktop:

1. Claude Code envía una solicitud a través de MCP
2. AppleScript activa Claude Desktop y crea una nueva conversación
3. La solicitud se escribe en Claude Desktop
4. El servidor pregunta a Claude Desktop por la respuesta
5. Una vez detectada la respuesta, se analiza y se devuelve a Claude Code

Solución de problemas

Problemas comunes

1. "Fallo en la ejecución de AppleScript

   • Asegúrese de que Claude Desktop está instalado y en ejecución
   • Compruebe los permisos de accesibilidad
   • Pruebe a ejecutar el servidor con un nivel de registro superior: LOG_LEVEL=3

2. "Tiempo de respuesta agotado"

   • Aumente el parámetro de tiempo de espera: timeout: 60 (60 segundos)
   • Para consultas complejas, utilice tiempos de espera más largos: timeout: 120 (2 minutos)
   • Reduzca el intervalo de sondeo para una detección más rápida: pollingInterval: 0.5
   • Compruebe si Claude Desktop responde con normalidad
   • Asegúrese de que el sistema no está sometido a una carga pesada

3. "Permiso denegado"

   • Conceda permisos de accesibilidad a su terminal
   • Ejecute el comando build con los permisos adecuados

4. El servidor MCPse bloquea después de enviar solicitudesSi el servidor MCP se bloquea después de gestionar solicitudes, puede:

   • Desactivar el sondeo de respuestas (recomendado para mayor estabilidad):

     export SKIP_CLAUDE_POLLING=true

     Esto enviará el mensaje a Claude Desktop pero no intentará leer la respuesta.

   • Habilite el registro de depuración para ver lo que está sucediendo:

     export LOG_LEVEL=3

   • Compruebe la salida stderr - Todos los registros se escriben ahora en stderr para evitar interferencias con el protocolo MCP en stdout.

Limitaciones conocidas del sondeo de respuestas

El sondeo de respuesta puede ocasionalmente causar inestabilidad debido a:

• Duración de sondeo extendida (30 segundos por defecto)
• Lectura compleja de elementos de interfaz de usuario desde aplicaciones Electron
• Problemas de sincronización con la generación de respuestas de Claude

Considere el uso de SKIP_CLAUDE_POLLING=true para un funcionamiento más fiable si no necesita la lectura de respuestas.

Contribuciones

Agradecemos las contribuciones a MCP Claude Desktop Ya sea corrigiendo errores, añadiendo características o mejorando la documentación, tu ayuda es bienvenida.

Para empezar

1. Fork del repositorio
2. Clone su bifurcación:

   git clone https://github.com/YOUR_USERNAME/mcp-claude-desktop cd mcp-claude-desktop

3. Instala las dependencias:

   npm install

4. Crear una nueva rama:

   git checkout -b feature/your-feature-name

Flujo de trabajo de desarrollo

1. Realiza los cambios
2. Ejecute pruebas para asegurarse de que todo funciona:

   npm test

3. Ejecute

   linting

   para mantener la calidad del código:

   npm run lint

4. Ejecuta la comprobación de tipos:

   npm run typecheck

5. Construir el proyecto:

   npm run build

Pautas de estilo de código

• Utilice TypeScript para todo el código fuente
• Siga el estilo de código existente (impuesto por ESLint)
• Escribir mensajes de confirmación significativos
• Añadir pruebas para las nuevas características
• Actualice la documentación según sea necesario

Envío de cambios

1. Confirma tus cambios con un mensaje descriptivo:

   git commit -m "feat: add support for conversation history"

2. Envíalo a tu bifurcación:

   git push origin feature/your-feature-name

3. Crear una Pull Request en GitHub

Directrices para las solicitudes de extracción

• Proporciona una descripción clara de los cambios
• Haz referencia a cualquier problema relacionado
• Asegúrate de que se superan todas las pruebas
• Actualizar README si se añaden nuevas características
• Responder a los comentarios sobre la revisión del código

Notificación de problemas

• Utilice GitHub Issues para informar de errores
• Incluya la versión de macOS y la versión de Node.js
• Proporcione los pasos para reproducir el problema
• Incluya mensajes de error o registros relevantes

Solicitudes de funciones

• Abre una incidencia para comentar nuevas funciones
• Explique el caso de uso y los beneficios
• Esté abierto a comentarios y enfoques alternativos

Licencia

MIT