Help Scout

You can connect Claude and other AI assistants to Help Scout data with secure, scalable MCP integration. This server enables advanced search, conversation analysis, and seamless integration with Help Scout through MCP-compatible clients.

How to use

You operate the Help Scout MCP Server from a client that supports the MCP protocol. Start the server using the configuration provided, then connect your MCP-enabled application to the server’s endpoint. Use the listing tool to browse conversations or the content search tool to find tickets based on terms, date ranges, or inbox filters. Leverage the analysis tools to retrieve summaries, thread histories, and current server time for time-relative queries. Ensure your credentials are active and your application has the required scopes or permissions.

How to install

Prerequisites include Node.js 18 or newer, a Help Scout account with API access, and an OAuth2 app or Personal Access Token. Claude Desktop is supported for DXT-based setups, but MCP clients can work with any MCP-compatible client.

Install steps for a standard local setup:

# Prerequisites
# 1) Install Node.js 18+
# 2) Prepare Help Scout credentials (OAuth2 or PAT)
# 3) Install dependencies and build
git clone https://github.com/drewburchfield/help-scout-mcp-server.git
cd help-scout-mcp-server
npm install
npm run build

# Create credentials file
# OAuth2 example
echo "HELPSCOUT_CLIENT_ID=your-client-id" > .env
echo "HELPSCOUT_CLIENT_SECRET=your-client-secret" >> .env

# Start the server
npm start

Configuring the server using the supported options:

{
  "mcpServers": {
    "helpscout": {
      "command": "npx",
      "args": ["help-scout-mcp-server"],
      "env": {
        "HELPSCOUT_CLIENT_ID": "your-client-id",
        "HELPSCOUT_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Alternative: run with Docker (no local install required):

docker run -e HELPSCOUT_CLIENT_ID="your-client-id" \
  -e HELPSCOUT_CLIENT_SECRET="your-client-secret" \
  drewburchfield/help-scout-mcp-server

Alternative: run directly from the CLI (no container):

HELPSCOUT_CLIENT_ID="your-client-id" \
HELPSCOUT_CLIENT_SECRET="your-client-secret" \
npx help-scout-mcp-server

Additional configuration and credentials

Get API credentials from Help Scout: use OAuth2 Client Credentials or a Personal Access Token. For OAuth2, create a Private App in Help Scout to obtain a Client ID and Client Secret. For a Personal Access Token, generate a token from your Help Scout profile.

Security and access control

The server supports PII redaction and secure token handling, with comprehensive audit logs and rate-limiting. Use the most restrictive credentials appropriate for your environment and rotate credentials regularly.

Troubleshooting and tips

If you encounter authentication issues, verify that your Client ID and Secret are correct and that the selected credential type matches your Help Scout configuration. For connection timeouts, check network access to the Help Scout API and consider increasing client-side or server-side timeouts. If search results are empty, confirm you selected the correct tool (listing vs content search) and that you have access to the specified inboxes.

Tools & capabilities overview

This MCP server exposes a set of tools to search, summarize, and retrieve conversation data from Help Scout. You can list recent conversations, perform content-based searches, and retrieve summaries or full threads for deeper analysis.

Available tools

searchConversations

List recent conversations with optional filters. Use to enumerate conversations when you don’t supply a specific search term.

comprehensiveConversationSearch

Search conversations by terms across content and metadata to locate specific tickets or messages.

advancedConversationSearch

Boolean and field-based search to filter by email, content terms, status, and more.

searchInboxes

Find and list available inboxes by name or identifier.

getConversationSummary

Retrieve a concise summary of a customer message and the latest staff reply.

getThreads

Fetch the complete message history for a conversation.

getServerTime

Return the current server timestamp for time-relative queries.