Help Scout

Um servidor MCP que permite que assistentes de IA interajam com dados do Help Scout, como clientes e conversas.

Documentação

Um servidor MCP que dá aos assistentes de IA acesso direto às suas caixas de entrada do Help Scout, conversas, clientes, organizações, tópicos e base de conhecimento do Docs. Pesquise tickets, obtenha contexto de clientes e contas, inspecione artigos, identifique padrões e obtenha respostas sem sair do seu editor ou janela de chat.

Construído por um cliente do Help Scout que queria dar superpoderes à sua equipe de suporte. Se você gerencia conversas com clientes no Help Scout e quer que a IA ajude você a trabalhar mais rápido, isto é para você.

O Que Você Pode Fazer

Pesquisar conversas por palavra-chave, intervalo de datas, status, tag, domínio de e-mail ou número do ticket
Consultar clientes por nome, sintaxe de consulta avançada ou endereço de e-mail exato
Explorar organizações com navegação direta por clientes e conversas
Inspecionar detalhes da conversa com metadados brutos do ticket, resumos, tópicos completos, anexos e fonte original
Carregar o histórico completo do tópico no contexto antes de redigir uma resposta
Obter resumos de conversas com a mensagem original do cliente e a resposta mais recente da equipe
Pesquisar e recuperar artigos do Docs pela API separada do Help Scout Docs
Obter relatórios e metadados do Help Scout para empresa, conversas, Docs, canais, produtividade, satisfação, usuários, equipes, usuários do sistema, status, roteamento e webhooks
Monitorar a atividade da caixa de entrada em várias caixas com uma única consulta
Agir com gravações opcionais: redigir respostas, notas internas, tags, status, atribuição, adiar e muito mais, tudo desativado por padrão
Reduzir o tamanho das mensagens com redação opcional do conteúdo e acesso restrito à caixa de entrada

Início Rápido

Claude Desktop e Claude Cowork (Recomendado)

Instalação em um clique usando Extensões de Desktop. Uma única instalação cobre sessões de Chat e Cowork no aplicativo de desktop do Claude.

Baixe o arquivo .mcpb mais recente dos lançamentos
Clique duas vezes para instalar (ou arraste para o Claude Desktop)
Insira seu App ID e App Secret do Help Scout nas configurações da extensão; as configurações também incluem alternâncias para redação de mensagens e a superfície de gravação opcional
Reinicie o Claude Desktop

Se as ferramentas não aparecerem em uma sessão do Cowork, atualize o aplicativo de desktop para a versão mais recente e inicie uma nova sessão. (Passo a passo do Cowork)

Opcional: adicione a habilidade helpscout-navigator para que o Claude escolha a operação certa mais rápido. Vá em Personalizar, clique em + > Adicionar marketplace do GitHub, insira drewburchfield/help-scout-mcp-server e instale helpscout-navigator.

Claude Code

Registre o servidor e, opcionalmente, adicione a habilidade helpscout-navigator, que ensina o Claude a escolher a operação certa 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

Depois, para a habilidade de navegação:

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

O servidor sozinho fornece as ferramentas; a habilidade também ensina a IA a usá-las bem.

Para Cursor, VS Code e Outros Clientes MCP

Adicione ao arquivo de configuração do seu cliente MCP (por exemplo, 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

Obtendo Suas Credenciais de API

Vá em Help Scout > Meus Aplicativos > Criar Aplicativo Privado
Copie seu App ID e App Secret

O Help Scout usa exclusivamente o fluxo OAuth2 Client Credentials. Tokens de Acesso Pessoal não são suportados. O aplicativo autentica como o usuário que o criou, com as permissões desse usuário; não há seleção separada de escopo, por isso o controle de gravação do servidor fica desativado por padrão.

Interface do Help Scout	Variável de Ambiente
App ID	`HELPSCOUT_APP_ID`
App Secret	`HELPSCOUT_APP_SECRET`

Nomes alternativos HELPSCOUT_CLIENT_ID / HELPSCOUT_CLIENT_SECRET também são suportados.

As ferramentas da base de conhecimento do Docs usam a API v1 do Help Scout Docs, que é separada da API do Mailbox. Defina HELPSCOUT_DOCS_API_KEY apenas se quiser usar listDocs*, searchDocsArticles, getDocsArticle ou ferramentas de redirecionamento.

Ferramentas

O servidor anuncia três ferramentas que juntas alcançam todas as operações de leitura suportadas (55 nas APIs do Mailbox e Docs):

Ferramenta	Finalidade
`search_help_scout`	Encontrar operações por intenção ("histórico de conversas do cliente", "relatório de satisfação")
`describe_help_scout`	Carregar os esquemas completos de entrada das operações selecionadas
`read_help_scout`	Executar uma operação: `{ "name": "getThreads", "arguments": { ... } }`

Isso mantém a superfície anunciada pequena o suficiente para que clientes de IA não se afoguem em esquemas, enquanto toda capacidade de leitura fica a uma busca de distância. As operações no registro atual também permanecem chamáveis diretamente pelo nome. Ferramentas removidas na consolidação v2.0.0 (por exemplo, comprehensiveConversationSearch, structuredConversationFilter e searchInboxes) não são; suas capacidades vivem em searchConversations e listAllInboxes.

Uma quarta ferramenta opcional, write_help_scout, aparece apenas quando um operador ativa gravações. Veja Operações de gravação (opt-in).

Para o contrato de compatibilidade MCP e o roteiro, veja:

Qual operação devo usar?

Execute qualquer uma delas via read_help_scout:

Tarefa	Operação	Exemplo
Listar tickets recentes	`searchConversations`	"Mostre-me tickets ativos desta semana"
Encontrar por palavra-chave	`searchConversations` (`contentTerms`)	"Encontre conversas sobre erros de cobrança"
Consultar um número de ticket	`searchConversations` (`conversationNumber`)	"Mostre-me o ticket #42839"
Filtros complexos	`searchConversations` (`emailDomain`, `tag`)	"Todas as conversas @acme.com marcadas como urgentes"
Navegar por clientes	`listCustomers`	"Mostre clientes chamados Jane"
Encontrar um cliente por e-mail	`searchCustomersByEmail`	"Encontre o cliente jane@acme.com"
Inspecionar um perfil de cliente	`getCustomer`	"Abra o cliente 12345"
Obter canais de contato do cliente	`getCustomerContacts`	"Mostre detalhes de contato do cliente 12345"
Navegar por organizações	`listOrganizations`	"Mostre as organizações mais movimentadas"
Inspecionar uma organização	`getOrganization`	"Abra a organização 456"
Listar clientes em uma organização	`getOrganizationMembers`	"Quem pertence à organização 456?"
Listar conversas da organização	`getOrganizationConversations`	"Mostre o histórico de suporte da organização 456"
Detalhe bruto da conversa	`getConversation`	"Abra a conversa 12345 com metadados completos"
Visão geral rápida da conversa	`getConversationSummary`	"Resuma esta conversa"
Histórico completo de mensagens	`getThreads`	"Mostre-me o tópico completo"
Inspecionar campos, pastas ou roteamento da caixa de entrada	`getInbox` (`include`)	"Mostre o roteamento da caixa de entrada 359402" (`include: ["routing"]`)
Pesquisar artigos do Docs	`searchDocsArticles`	"Encontre artigos da base de conhecimento sobre reembolsos"
Recuperar um artigo do Docs	`getDocsArticle`	"Abra o artigo 123 do Docs"
Hora atual do host MCP	`getServerTime`	Usado para buscas relativas ao tempo

As caixas de entrada são descobertas automaticamente quando o servidor se conecta. Os agentes de IA recebem os IDs das caixas de entrada automaticamente nas instruções, então nenhuma etapa de consulta é necessária.

Operações de gravação (opt-in)

Uma instalação padrão é somente leitura. Ela anuncia as três ferramentas acima e nada mais, inalterado desde a 2.0. As gravações existem apenas depois que um operador define uma flag.

Flag	O que adiciona
`HELPSCOUT_ENABLE_WRITES=true`	Uma quarta ferramenta, `write_help_scout`, com 11 operações de conversa de nível 1
`HELPSCOUT_ENABLE_CUSTOMER_VISIBLE_WRITES=true`	Mais duas operações na mesma ferramenta: `sendReply` e `publishDraft`

O nível 1 cobre rascunhos de respostas, notas internas, mudanças de status, atribuir e desatribuir, adicionar e remover tags, valores de campos personalizados, adiar e reativar, e mover uma conversa para outra caixa de entrada. Nada disso envia e-mail a ninguém: um rascunho é salvo sem envio, e uma nota é visível apenas para colegas de equipe.

O nível 2 é o único caminho que alcança um cliente, e precisa de ambas as flags. Toda chamada a sendReply ou publishDraft também deve incluir uma confirmação nomeando a operação e o destino:

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

Confirmação ausente, falsa ou incompatível é recusada antes que qualquer coisa chegue ao Help Scout. Exclusões e gravações de configuração administrativa são deliberadamente não expostas, sob qualquer flag.

Defina "dryRun": true em qualquer gravação para validar os argumentos e ver a solicitação exata que seria enviada, sem contatar o Help Scout.

Regras completas: contrato da ferramenta de gravação.

Configuração

Variável	Descrição	Padrão
`HELPSCOUT_APP_ID`	App ID de Meus Aplicativos do Help Scout	Obrigatório
`HELPSCOUT_APP_SECRET`	App Secret de Meus Aplicativos do Help Scout	Obrigatório
`HELPSCOUT_DEFAULT_INBOX_ID`	Restringir buscas a uma caixa de entrada específica	Nenhum (todas as caixas)
`HELPSCOUT_BASE_URL`	Endpoint da API do Help Scout	`https://api.helpscout.net/v2/`
`HELPSCOUT_DOCS_API_KEY`	Chave opcional da API do Docs para ferramentas da base de conhecimento	Nenhum
`HELPSCOUT_DOCS_BASE_URL`	Endpoint da API do Help Scout Docs	`https://docsapi.helpscout.net/v1/`
`REDACT_MESSAGE_CONTENT`	Substituir corpos de mensagens por espaços reservados	`false`
`HELPSCOUT_ENABLE_WRITES`	Anunciar `write_help_scout` com as gravações de conversa de nível 1	Não definido (`false`)
`HELPSCOUT_ENABLE_CUSTOMER_VISIBLE_WRITES`	Também habilitar `sendReply` e `publishDraft`, que enviam e-mail ao cliente	Não definido (`false`)
`CACHE_TTL_SECONDS`	Duração do cache para respostas da API	`300`
`LOG_LEVEL`	Nível de detalhe do registro (`error`, `warn`, `info`, `debug`)	`info`

Compatibilidade

Funciona com qualquer cliente compatível com MCP:

Categoria	Clientes
Assistentes de IA	Claude Desktop (Chat e Cowork), Goose e outros assistentes habilitados para MCP
Editores de Código	Cursor, VS Code, Windsurf, Continue.dev
Linha de Comando	Claude Code, Codex, Gemini CLI, OpenCode
Personalizado	Qualquer aplicativo que implemente o padrão MCP

Segurança e Privacidade

Construído pensando em equipes focadas em segurança:

Redação opcional do conteúdo das mensagens. Os corpos das mensagens são incluídos por padrão. Defina REDACT_MESSAGE_CONTENT=true para substituir os corpos de conversas e tópicos por espaços reservados para análise de contexto reduzido. Isso não é um limite de conformidade e não remove todos os identificadores de clientes.
Autenticação segura. OAuth2 Client Credentials com renovação automática de token.
Tratamento de limites de taxa. Nova tentativa automática com backoff exponencial em respostas 429.
Acesso restrito. A configuração opcional de caixa de entrada padrão limita o que a IA pode pesquisar.

Solução de Problemas

Falha na autenticação? Verifique se suas credenciais funcionam diretamente com o 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 busca vazios? Causas comuns:

Esquecer que searchConversations é a única ferramenta de busca: use contentTerms/subjectTerms para busca por palavra-chave, filtros simples para listagem
ID de caixa de entrada incorreto. Verifique os IDs nas instruções do servidor, não valores adivinhados.
Termos de busca muito restritos. Tente termos mais amplos ou um intervalo de tempo maior.

Precisa de mais detalhes? Ative o registro de depuração:

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

Desenvolvimento

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

Contribuições são bem-vindas. Certifique-se de que testes, verificação de tipos e linting passem antes de enviar um PR.

Suporte

Licença

Licença MIT - veja LICENSE para detalhes.