Help Scout

Un servidor MCP que permite a los asistentes de IA interactuar con datos de Help Scout, como clientes y conversaciones.

Documentación

Un servidor MCP que brinda a los asistentes de IA acceso directo a tus bandejas de entrada, conversaciones, clientes, organizaciones, hilos y base de conocimiento de Docs de Help Scout. Busca tickets, obtén contexto de clientes y cuentas, inspecciona artículos, detecta patrones y obtén respuestas sin salir de tu editor o ventana de chat.

Creado por un cliente de Help Scout que quería darle superpoderes a su equipo de soporte. Si gestionas conversaciones de clientes en Help Scout y quieres que la IA te ayude a trabajar más rápido, esto es para ti.

Lo que puedes hacer

Buscar conversaciones por palabra clave, rango de fechas, estado, etiqueta, dominio de correo o número de ticket
Consultar clientes por nombre, sintaxis de consulta avanzada o dirección de correo exacta
Explorar organizaciones con recorrido directo de clientes y conversaciones
Inspeccionar el detalle de conversaciones con metadatos crudos del ticket, resúmenes, hilos completos, adjuntos y fuente original
Cargar el historial completo del hilo en el contexto antes de redactar una respuesta
Obtener resúmenes de conversaciones con el mensaje original del cliente y la última respuesta del equipo
Buscar y recuperar artículos de Docs desde la API de Docs de Help Scout, separada de la API de Mailbox
Obtener informes y metadatos de Help Scout para empresa, conversaciones, Docs, canales, productividad, satisfacción, usuarios, equipos, usuarios del sistema, estados, enrutamiento y webhooks
Monitorear la actividad de bandejas de entrada en múltiples bandejas con una sola consulta
Actuar con escrituras opcionales: redactar respuestas, notas internas, etiquetas, estado, asignación, posponer y más, todo desactivado por defecto
Reducir la carga de mensajes con redacción opcional del contenido y acceso restringido a bandejas de entrada

Inicio rápido

Claude Desktop y Claude Cowork (Recomendado)

Instalación con un clic mediante Desktop Extensions. Una sola instalación cubre tanto las sesiones de Chat como de Cowork en la aplicación de escritorio de Claude.

Descarga el último archivo .mcpb desde releases
Haz doble clic para instalar (o arrastra a Claude Desktop)
Ingresa tu App ID y App Secret de Help Scout en la configuración de la extensión; la configuración también incluye interruptores para la redacción de mensajes y la superficie de escritura opcional
Reinicia Claude Desktop

Si las herramientas no aparecen en una sesión de Cowork, actualiza la aplicación de escritorio a la última versión e inicia una sesión nueva. (Guía de Cowork)

Opcional: agrega la habilidad helpscout-navigator para que Claude elija la operación correcta más rápido. Ve a Customize, haz clic en + > Add marketplace from GitHub, ingresa drewburchfield/help-scout-mcp-server e instala helpscout-navigator.

Claude Code

Registra el servidor y luego agrega opcionalmente la habilidad helpscout-navigator, que enseña a Claude a elegir la operación correcta para cada consulta.

claude mcp add helpscout \
  --env HELPSCOUT_APP_ID=your-app-id \
  --env HELPSCOUT_APP_SECRET=your-app-secret \
  -- npx -y help-scout-mcp-server

Luego, para la habilidad de navegación:

Ejecuta /plugin marketplace add drewburchfield/help-scout-mcp-server
Ejecuta /plugin install helpscout-navigator

El servidor por sí solo te da las herramientas; la habilidad también enseña a la IA a usarlas bien.

Para Cursor, VS Code y otros clientes MCP

Agrega al archivo de configuración de tu cliente MCP (p. ej., claude_desktop_config.json, .cursor/mcp.json):

{
  "mcpServers": {
    "helpscout": {
      "command": "npx",
      "args": ["help-scout-mcp-server@2.1.0"],
      "env": {
        "HELPSCOUT_APP_ID": "your-app-id",
        "HELPSCOUT_APP_SECRET": "your-app-secret",
        "HELPSCOUT_DOCS_API_KEY": "optional-docs-api-key"
      }
    }
  }
}

Docker

docker run -e HELPSCOUT_APP_ID="your-app-id" \
  -e HELPSCOUT_APP_SECRET="your-app-secret" \
  -e HELPSCOUT_DOCS_API_KEY="optional-docs-api-key" \
  drewburchfield/help-scout-mcp-server:2.1.0

Obtención de tus credenciales de API

Ve a Help Scout > My Apps > Create Private App
Copia tu App ID y App Secret

Help Scout usa exclusivamente el flujo OAuth2 de Client Credentials. No se admiten tokens de acceso personal. La aplicación se autentica como el usuario que la creó, con los permisos de ese usuario; no hay selección de alcance separada, por eso la puerta de escritura del servidor está desactivada por defecto.

Interfaz de Help Scout	Variable de entorno
App ID	`HELPSCOUT_APP_ID`
App Secret	`HELPSCOUT_APP_SECRET`

También se admiten los nombres alternativos HELPSCOUT_CLIENT_ID / HELPSCOUT_CLIENT_SECRET.

Las herramientas de la base de conocimiento de Docs usan la API de Docs v1 de Help Scout, que es independiente de la API de Mailbox. Configura HELPSCOUT_DOCS_API_KEY solo si quieres usar listDocs*, searchDocsArticles, getDocsArticle o herramientas de redirección.

Herramientas

El servidor anuncia tres herramientas que juntas cubren todas las operaciones de lectura admitidas (55 entre las APIs de Mailbox y Docs):

Herramienta	Propósito
`search_help_scout`	Encuentra operaciones por intención ("historial de conversaciones del cliente", "informe de satisfacción")
`describe_help_scout`	Carga los esquemas de entrada completos de las operaciones seleccionadas
`read_help_scout`	Ejecuta una operación: `{ "name": "getThreads", "arguments": { ... } }`

Esto mantiene la superficie anunciada lo suficientemente pequeña para que los clientes de IA no se ahoguen en esquemas, mientras que cada capacidad de lectura sigue a una búsqueda de distancia. Las operaciones del registro actual también siguen siendo invocables por nombre directamente. Los nombres de herramientas eliminados en la consolidación v2.0.0 (por ejemplo, comprehensiveConversationSearch, structuredConversationFilter y searchInboxes) no lo son; sus capacidades viven en searchConversations y listAllInboxes.

Una cuarta herramienta opcional, write_help_scout, aparece solo cuando un operador activa las escrituras. Consulta Operaciones de escritura (opt-in).

Para el contrato de compatibilidad MCP y la hoja de ruta, consulta:

¿Qué operación debería usar?

Ejecuta cualquiera de estas mediante read_help_scout:

Tarea	Operación	Ejemplo
Listar tickets recientes	`searchConversations`	"Muéstrame los tickets activos de esta semana"
Buscar por palabra clave	`searchConversations` (`contentTerms`)	"Encuentra conversaciones sobre errores de facturación"
Consultar un número de ticket	`searchConversations` (`conversationNumber`)	"Muéstrame el ticket #42839"
Filtros complejos	`searchConversations` (`emailDomain`, `tag`)	"Todas las conversaciones de @acme.com etiquetadas como urgentes"
Explorar clientes	`listCustomers`	"Muestra los clientes llamados Jane"
Encontrar un cliente por correo	`searchCustomersByEmail`	"Encuentra al cliente jane@acme.com"
Inspeccionar un perfil de cliente	`getCustomer`	"Abre el cliente 12345"
Obtener canales de contacto del cliente	`getCustomerContacts`	"Muestra los datos de contacto del cliente 12345"
Explorar organizaciones	`listOrganizations`	"Muestra las organizaciones más activas"
Inspeccionar una organización	`getOrganization`	"Abre la organización 456"
Listar clientes de una organización	`getOrganizationMembers`	"¿Quién pertenece a la organización 456?"
Listar conversaciones de la organización	`getOrganizationConversations`	"Muestra el historial de soporte de la organización 456"
Detalle crudo de conversación	`getConversation`	"Abre la conversación 12345 con metadatos completos"
Resumen rápido de conversación	`getConversationSummary`	"Resume esta conversación"
Historial completo de mensajes	`getThreads`	"Muéstrame el hilo completo"
Inspeccionar campos, carpetas o enrutamiento de bandeja	`getInbox` (`include`)	"Muestra el enrutamiento de la bandeja 359402" (`include: ["routing"]`)
Buscar artículos de Docs	`searchDocsArticles`	"Encuentra artículos de la base de conocimiento sobre reembolsos"
Recuperar un artículo de Docs	`getDocsArticle`	"Abre el artículo de Docs 123"
Hora actual del host MCP	`getServerTime`	Se usa para búsquedas relativas al tiempo

Las bandejas de entrada se descubren automáticamente cuando el servidor se conecta. Los agentes de IA reciben los IDs de bandeja en sus instrucciones automáticamente, por lo que no se necesita ningún paso de búsqueda.

Operaciones de escritura (opt-in)

Una instalación predeterminada es de solo lectura. Anuncia las tres herramientas anteriores y nada más, sin cambios desde 2.0. Las escrituras existen solo después de que un operador establece una bandera.

Bandera	Qué agrega
`HELPSCOUT_ENABLE_WRITES=true`	Una cuarta herramienta, `write_help_scout`, con 11 operaciones de conversación de nivel 1
`HELPSCOUT_ENABLE_CUSTOMER_VISIBLE_WRITES=true`	Dos operaciones más en esa misma herramienta: `sendReply` y `publishDraft`

El nivel 1 cubre respuestas en borrador, notas internas, cambios de estado, asignar y desasignar, agregar y quitar etiquetas, valores de campos personalizados, posponer y reanudar, y mover una conversación a otra bandeja de entrada. Nada de esto envía correos a nadie: un borrador se guarda sin enviar y una nota solo es visible para los compañeros de equipo.

El nivel 2 es la única vía que llega a un cliente y requiere ambas banderas. Cada llamada a sendReply o publishDraft también debe incluir una confirmación que nombre la operación y el destino:

{
  "name": "sendReply",
  "arguments": { "conversationId": "12345", "text": "..." },
  "confirm": true,
  "confirmOperation": "sendReply",
  "targetId": "12345"
}

La confirmación faltante, falsa o no coincidente se rechaza antes de que cualquier cosa llegue a Help Scout. Las eliminaciones y las escrituras de configuración de administrador no se exponen deliberadamente, bajo ninguna bandera.

Configura "dryRun": true en cualquier escritura para validar los argumentos y ver la solicitud exacta que se enviaría, sin contactar a Help Scout.

Reglas completas: contrato de la herramienta de escritura.

Configuración

Variable	Descripción	Predeterminado
`HELPSCOUT_APP_ID`	App ID de Help Scout My Apps	Requerido
`HELPSCOUT_APP_SECRET`	App Secret de Help Scout My Apps	Requerido
`HELPSCOUT_DEFAULT_INBOX_ID`	Limita las búsquedas a una bandeja específica	Ninguna (todas las bandejas)
`HELPSCOUT_BASE_URL`	Endpoint de la API de Help Scout	`https://api.helpscout.net/v2/`
`HELPSCOUT_DOCS_API_KEY`	Clave de API de Docs opcional para herramientas de base de conocimiento	Ninguna
`HELPSCOUT_DOCS_BASE_URL`	Endpoint de la API de Docs de Help Scout	`https://docsapi.helpscout.net/v1/`
`REDACT_MESSAGE_CONTENT`	Reemplaza los cuerpos de mensajes con marcadores de posición	`false`
`HELPSCOUT_ENABLE_WRITES`	Anunciar `write_help_scout` con las escrituras de conversación de nivel 1	Sin configurar (`false`)
`HELPSCOUT_ENABLE_CUSTOMER_VISIBLE_WRITES`	También habilita `sendReply` y `publishDraft`, que envían correo al cliente	Sin configurar (`false`)
`CACHE_TTL_SECONDS`	Duración de caché para respuestas de API	`300`
`LOG_LEVEL`	Verbosidad de registro (`error`, `warn`, `info`, `debug`)	`info`

Compatibilidad

Funciona con cualquier cliente compatible con MCP:

Categoría	Clientes
Asistentes de IA	Claude Desktop (Chat y Cowork), Goose y otros asistentes con MCP habilitado
Editores de código	Cursor, VS Code, Windsurf, Continue.dev
Línea de comandos	Claude Code, Codex, Gemini CLI, OpenCode
Personalizado	Cualquier aplicación que implemente el estándar MCP

Seguridad y privacidad

Diseñado pensando en equipos conscientes de la seguridad:

Redacción opcional del contenido de mensajes. Los cuerpos de mensajes se incluyen por defecto. Configura REDACT_MESSAGE_CONTENT=true para reemplazar los cuerpos de conversaciones e hilos con marcadores de posición para un análisis de menor contexto. Esto no es un límite de cumplimiento y no elimina todos los identificadores de clientes.
Autenticación segura. OAuth2 Client Credentials con renovación automática de tokens.
Manejo de límites de tasa. Reintento automático con retroceso exponencial en respuestas 429.
Acceso restringido. La configuración opcional de bandeja predeterminada limita lo que la IA puede buscar.

Solución de problemas

¿Falló la autenticación? Verifica que tus credenciales funcionen directamente con Help Scout:

curl -X POST https://api.helpscout.net/v2/oauth2/token \
  -d "grant_type=client_credentials&client_id=$HELPSCOUT_APP_ID&client_secret=$HELPSCOUT_APP_SECRET"

¿Resultados de búsqueda vacíos? Causas comunes:

Olvidar que searchConversations es la única herramienta de búsqueda: usa contentTerms/subjectTerms para búsqueda por palabra clave y filtros simples para listar
ID de bandeja no coincidente. Verifica los IDs de las instrucciones del servidor, no valores adivinados.
Términos de búsqueda demasiado específicos. Prueba términos más amplios o un rango de tiempo más largo.

¿Necesitas más detalle? Habilita el registro de depuración:

LOG_LEVEL=debug npx help-scout-mcp-server@2.1.0

Desarrollo

git clone https://github.com/drewburchfield/help-scout-mcp-server.git
cd help-scout-mcp-server
npm install && npm run build
npm start

npm test           # Run tests
npm run type-check # TypeScript validation
npm run lint       # Linting
npm run dev        # Development server with auto-reload

Las contribuciones son bienvenidas. Asegúrate de que las pruebas, la verificación de tipos y el linting pasen antes de enviar un PR.

Soporte

Licencia

Licencia MIT: consulta LICENSE para más detalles.