Claude Desktop MCP

Un servidor MCP para integrarse con la aplicación Claude Desktop en macOS. Requiere que la aplicación Claude Desktop esté instalada y configurada.

GitHub
1
Prueba este MCPPatrocinado

Documentación

MCP Claude Desktop

Un servidor de Model Context Protocol (MCP) que permite a Claude Code comunicarse con Claude Desktop. Este servidor permite a Claude Code enviar prompts a Claude Desktop y consultar las respuestas.

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

Características

  • Enviar prompts desde Claude Code a Claude Desktop
  • Consulta automática de respuestas con tiempo de espera configurable
  • Listar conversaciones disponibles en Claude Desktop
  • Manejo de errores y lógica de reintentos
  • Registro completo de actividades

Instalación

Puedes instalar y usar este servidor MCP de dos maneras:

Opción 1: Usando npx (Recomendado)

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

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

Opción 2: Instalación Local

  1. Clona este repositorio:
git clone https://github.com/dpaluy/mcp-claude-desktop
cd mcp-claude-desktop
  1. Instala las dependencias:
npm install
  1. Compila el proyecto:
npm run build
  1. Configura 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 otorgados para AppleScript

Otorgar Permisos de Accesibilidad

  1. Abre Preferencias del Sistema > Seguridad y Privacidad > Privacidad
  2. Selecciona "Accesibilidad" en la barra lateral izquierda
  3. Haz clic en el candado para realizar cambios
  4. Agrega Terminal (o tu aplicación de terminal) a las aplicaciones permitidas
  5. Reinicia tu terminal

Herramientas MCP

Este servidor MCP proporciona dos herramientas:

ask

  • Propósito: Enviar un prompt a Claude Desktop y obtener una respuesta
  • Parámetros:
    • prompt: El texto a enviar a Claude Desktop (obligatorio)
    • conversationId: ID opcional para continuar una conversación específica
    • timeout: Tiempo de espera de respuesta en segundos (opcional, predeterminado: 30, máximo: 300)
    • pollingInterval: Frecuencia de verificación de respuesta en segundos (opcional, predeterminado: 1.5, mínimo: 0.5)

get_conversations

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

Uso

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

Uso General

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

Uso básico:

  • Herramienta: ask
  • Parámetros: { "prompt": "What is dependency injection?" }

Con tiempo de espera personalizado:

  • Herramienta: ask
  • Parámetros: { "prompt": "Explain quantum computing", "timeout": 120 }

Con tiempo de espera e intervalo de consulta:

  • Herramienta: ask
  • Parámetros: { "prompt": "Quick question", "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 ejecutándose, puedes usar estas herramientas directamente en Claude:

Uso básico:

  • "Usa 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 de Claude Desktop"

Con tiempo de espera personalizado:

  • "Usa la herramienta ask con tiempo de espera 60 para preguntar a Claude Desktop: Explica la implementación del árbol B+"
  • "Usa ask con tiempo de espera 10 e intervalo de consulta 0.5 para preguntar a Claude Desktop: ¿Cuánto es 2+2?"

Importante: La configuración del servidor MCP (mostrada arriba) solo le indica a Claude cómo iniciar el servidor. Los parámetros de tiempo de espera e intervalo de consulta se especifican cuando usas 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 programáticamente. La herramienta puede:

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

Esta es una limitación de cómo las aplicaciones Electron exponen los elementos de interfaz a través de las APIs de accesibilidad. Cuando uses la herramienta ask, recibirás una confirmación de que el mensaje fue enviado, pero necesitarás revisar la ventana de Claude Desktop directamente para ver la respuesta.

Soluciones Alternativas

  1. Usar la API de Claude: Para acceso programático a las respuestas, considera usar la API de Claude directamente en lugar de la automatización de escritorio
  2. Verificación manual: Después de enviar un prompt, verifica manualmente la ventana de Claude Desktop para ver la respuesta
  3. Automatización unidireccional: Usa esta herramienta para escenarios donde solo necesitas enviar prompts sin leer respuestas

Integración con Comandos de Claude

Los Comandos de Claude te permiten crear flujos de trabajo reutilizables que combinan herramientas MCP. Este proyecto funciona perfectamente con los Comandos de Claude para habilitar automatización potente.

Ejemplo: Comando de Revisión de Código entre Pares

Hemos incluido un Comando de Claude de ejemplo que demuestra cómo usar MCP Claude Desktop para revisiones de código automatizadas. El comando usa git para analizar cambios recientes y los envía a Claude Desktop para obtener comentarios de revisión entre pares.

Configuración

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

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

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

Uso

El comando de revisión entre pares acepta hasta 3 argumentos:

  • description: Qué cambios revisar (ej., "corrección de autenticación")
  • polling_interval: Frecuencia de verificación de respuesta (predeterminado: 1.5s)
  • timeout: Tiempo máximo de espera para la respuesta (predeterminado: 30s)

Ejemplos:

# 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

Cómo Funciona

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

    • Estado actual de git
    • Estadísticas de commits recientes
    • Diff completo de los cambios
    • Nombre de la rama actual

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

    • Adecuación del código y calidad de implementación
    • Preocupaciones de seguridad o posibles errores
    • Calidad del código y mejores prácticas
    • Sugerencias de mejoras

  3. Manejo de Respuestas: Usa el mecanismo de consulta del servidor MCP para esperar la respuesta de Claude

  4. Generación de Resumen: Proporciona un resumen estructurado de:

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

Creando Tus Propios Comandos

Puedes crear Comandos de Claude personalizados que aprovechen 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. Usar las herramientas MCP con parámetros apropiados:

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

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

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

Desarrollo

Ejecutar en Modo de Desarrollo

npm run dev

Ejecutar Pruebas

npm test

Linting

npm run lint

Verificación de Tipos

npm run typecheck

API

Herramientas

ask

Envía un prompt a Claude Desktop y obtiene una respuesta.

Parámetros:

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

Respuesta:

String containing Claude's response

get_conversations

Obtiene una lista de conversaciones disponibles en Claude Desktop.

Parámetros: Ninguno

Respuesta:

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

Arquitectura

El servidor MCP usa AppleScript para comunicarse con Claude Desktop:

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

Solución de Problemas

Problemas Comunes

  1. "Error de ejecución de AppleScript"

    • Asegúrate de que Claude Desktop esté instalado y ejecutándose
    • Verifica los permisos de accesibilidad
    • Intenta ejecutar el servidor con un nivel de registro más alto: LOG_LEVEL=3

  2. "Tiempo de espera de respuesta agotado"

    • Aumenta el parámetro de tiempo de espera: timeout: 60 (60 segundos)
    • Para consultas complejas, usa tiempos de espera más largos: timeout: 120 (2 minutos)
    • Reduce el intervalo de consulta para una detección más rápida: pollingInterval: 0.5
    • Verifica si Claude Desktop está respondiendo normalmente
    • Asegúrate de que el sistema no esté bajo carga pesada

  3. "Permiso denegado"

    • Otorga permisos de accesibilidad a tu terminal
    • Ejecuta el comando de compilación con los permisos adecuados

  4. El Servidor MCP se Bloquea Después de Enviar Solicitudes Si el servidor MCP se bloquea después de manejar solicitudes, puedes:

    • Deshabilitar la consulta de respuestas (recomendado para estabilidad):

      export SKIP_CLAUDE_POLLING=true

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

    • Habilitar el registro de depuración para ver qué está sucediendo:

      export LOG_LEVEL=3

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

Limitaciones Conocidas con la Consulta de Respuestas

La consulta de respuestas puede causar inestabilidad ocasional debido a:

  • Duración extendida de la consulta (30 segundos predeterminado)
  • Lectura compleja de elementos de interfaz de aplicaciones Electron
  • Problemas de sincronización con la generación de respuestas de Claude

Considera usar SKIP_CLAUDE_POLLING=true para una operación más confiable si no necesitas leer respuestas.

Contribuciones

¡Damos la bienvenida a contribuciones a MCP Claude Desktop! Ya sea que estés corrigiendo errores, agregando funciones o mejorando la documentación, tu ayuda es apreciada.

Comenzando

  1. Haz un fork del repositorio
  2. Clona tu fork: 
    git clone https://github.com/YOUR_USERNAME/mcp-claude-desktop
cd mcp-claude-desktop
  3. Instala las dependencias: 
    npm install
  4. Crea una nueva rama: 
    git checkout -b feature/your-feature-name

Flujo de Trabajo de Desarrollo

  1. Realiza tus cambios
  2. Ejecuta las pruebas para asegurarte de que todo funcione: 
    npm test
  3. Ejecuta el linting para mantener la calidad del código: 
    npm run lint
  4. Ejecuta la verificación de tipos: 
    npm run typecheck
  5. Compila el proyecto: 
    npm run build

Pautas de Estilo de Código

  • Usa TypeScript para todo el código fuente
  • Sigue el estilo de código existente (aplicado por ESLint)
  • Escribe mensajes de commit significativos
  • Agrega pruebas para nuevas funciones
  • Actualiza la documentación según sea necesario

Envío de Cambios

  1. Haz commit de tus cambios con un mensaje descriptivo: 
    git commit -m "feat: add support for conversation history"
  2. Haz push a tu fork: 
    git push origin feature/your-feature-name
  3. Crea una Solicitud de Extracción (Pull Request) en GitHub

Pautas para Solicitudes de Extracción

  • Proporciona una descripción clara de los cambios
  • Haz referencia a cualquier problema relacionado
  • Asegúrate de que todas las pruebas pasen
  • Actualiza el README si agregas nuevas funciones
  • Sé receptivo a los comentarios de revisión de código

Reporte de Problemas

  • Usa Problemas de GitHub para reportar errores
  • Incluye la versión de macOS y la versión de Node.js
  • Proporciona pasos para reproducir el problema
  • Incluye mensajes de error o registros relevantes

Solicitudes de Funciones

  • Abre un problema para discutir nuevas funciones
  • Explica el caso de uso y los beneficios
  • Sé abierto a comentarios y enfoques alternativos

Licencia

MIT