← Back to directory
H

Help Scout MCP Server

Community
Connect AI assistants to your Help Scout tickets, customers, and knowledge base
Category
Other #25 of 230
Stars
★ 47 Popular
Transport
stdio (local process)
Runtime
Node.js · Docker
Credentials
API key / credential required
License
MIT
Last commit
Tools
4
67FMRS · C

A mature community-built Help Scout integration: 55 read operations covering conversations, customers, organizations, reports, and Docs via a three-tool gateway design that avoids schema overload. Writes are off by default and tiered (customer-visible operations require two flags plus explicit confirmation), with redaction, rate-limit retry, and optional inbox scoping. Documentation is thorough and installs are available via npm, Docker, and MCPB, but it is a third-party implementation, not an official Help Scout product.

Strongest · Documentation 17/20 Weakest · Reliability 9/20

Reliability
9/20
Security and permissions
15/20
Maintenance
12/20
Documentation
17/20
Setup experience
14/20
Why each score
Reliability 9/20
The README describes a three-tool gateway pattern (search_help_scout/describe_help_scout/read_help_scout) claiming coverage of 55 read operations, and references npm test/type-check/lint commands, but only the README and server.json were provided here — no actual source code, CI workflow files, or test contents were included. There is no way to confirm the declared behavior matches the real implementation or that errors/dependencies are actually controllable. Per the static calibration rule, without verifiable execution evidence (real CI plus committed tests covering key paths), reliability is capped at 12 and further reduced for the evidence gap.
Security and permissions 15/20
Credential handling looks reasonable: OAuth2 App ID/Secret and the Docs API key are all marked isSecret, and config examples use placeholders rather than real tokens. The default install is read-only; write access requires an operator to explicitly set env flags, and the customer-facing high-risk operations (sendReply/publishDraft) require an extra flag plus per-call confirm/confirmOperation/targetId triple confirmation, with deletes and admin-config writes explicitly excluded. The redaction feature is honestly caveated as not a compliance boundary and not removing all identifiers, which is a positive disclosure. However, all of this comes from README/manifest claims (untrusted evidence) — static review cannot verify the confirmation logic is actually enforced in code, so full marks are not warranted, though no red-line issue was found.
Maintenance 12/20
The project is MIT licensed, and the manifest shows a clear version (2.1.0) published to both npm and a Docker registry, indicating some release process. However, the material lacks evidence of commit history, release cadence, issue response times, dependency update practices, or a dedicated security disclosure channel — only GitHub Issues/Discussions are listed as support, which doesn't substitute for governance transparency. Star count and open-issue count are discovery signals only and are not credited, and missing evidence is treated as a deduction rather than assumed best case.
Documentation 17/20
Documentation is well-layered, covering install steps for multiple clients (Claude Desktop, Claude Code, Cursor/VS Code, Docker), credential acquisition, an operation reference table, a detailed write-gating and confirmation protocol with JSON examples, a configuration table with defaults, a troubleshooting section, and an honest caveat about the limits of message redaction. Points were deducted because several referenced internal guide files (e.g., mcp-tool-contract.md) were not available for review, and rate-limit/cost disclosure is thin, mentioning only automatic retry behavior.
Setup experience 14/20
Setup paths cover one-click mcpb install, a Claude Code CLI command, generic MCP client JSON config, and a Docker run example, with clear steps and complete config samples plus explicit multi-platform compatibility notes. However, since no CI workflow or test files were available to verify actual execution, setup is capped at 15 per the static calibration rule.

Static review · not runListed 2026-09-07

Read the FMRS scoring method →

Fit and risk

What it can accessUses the networkChanges third-party account data

Best for

  • Support teams using Help Scout who want AI assistants (especially Claude) to query tickets, customers, and knowledge base quickly
  • Engineers who want customer context without leaving their editor or chat window
  • Security-conscious teams needing read-by-default, auditable opt-in writes

Not for

  • Teams not using Help Scout as their help desk
  • Environments unwilling to grant AI access to support data
  • Users expecting out-of-the-box email sending, deletes, or admin config writes (deliberately not exposed)

Required permissions

  • Help Scout OAuth2 App ID and App Secret (required; authenticates as the creating user with their permissions)
  • Optional: HELPSCOUT_DEFAULT_INBOX_ID to scope searches
  • Optional: HELPSCOUT_DOCS_API_KEY for Docs knowledge base tools
  • Optional: HELPSCOUT_ENABLE_WRITES and HELPSCOUT_ENABLE_CUSTOMER_VISIBLE_WRITES for write operations

Risks and side effects

  • AI can access all support data (conversation content, customer and organization info); credential leakage risks data exposure
  • Message content is included by default; REDACT_MESSAGE_CONTENT is not a compliance boundary and does not remove all customer identifiers
  • When writes are enabled, the server can modify conversation status, tags, assignments, etc.; tier-2 operations (sendReply/publishDraft) email customers and require care despite confirmation mechanisms
  • Help Scout OAuth2 has no separate scope selection; the app acts with the creator's permissions, so shared credentials widen impact

Setup

Before you start

Runtime:Node.js · Docker

HELPSCOUT_APP_ID requiredsecret Help Scout OAuth2 App ID (HELPSCOUT_CLIENT_ID also accepted), from Help Scout > My Apps > Create Private App. Required.
HELPSCOUT_APP_SECRET requiredsecret Help Scout OAuth2 App Secret (HELPSCOUT_CLIENT_SECRET also accepted), obtained with the App ID. Required.
HELPSCOUT_DOCS_API_KEY optionalsecret Optional Help Scout Docs API key, needed only for knowledge base (Docs) tools.
Other optional settings (8)
HELPSCOUT_DEFAULT_INBOX_ID optional Optional; scopes searches to a specific inbox.
REDACT_MESSAGE_CONTENT optional Optional; set to true to replace message bodies with placeholders.
HELPSCOUT_ENABLE_WRITES optional Optional; set to true to advertise the write_help_scout tool with tier-1 conversation writes.
HELPSCOUT_ENABLE_CUSTOMER_VISIBLE_WRITES optional Optional; requires HELPSCOUT_ENABLE_WRITES, enables sendReply and publishDraft which email the customer.
CACHE_TTL_SECONDS optional Optional; API response cache duration, default 300.
LOG_LEVEL optional Optional; logging verbosity (error/warn/info/debug), default info.
HELPSCOUT_BASE_URL optional Optional; Help Scout API endpoint, default https://api.helpscout.net/v2/.
HELPSCOUT_DOCS_BASE_URL optional Optional; Help Scout Docs API endpoint, default https://docsapi.helpscout.net/v1/.
  1. In Help Scout, go to My Apps > Create Private App and copy the App ID and App Secret. 2a. Claude Desktop/Cowork: download the latest .mcpb from Releases, double-click to install, enter credentials in extension settings, and restart. 2b. Claude Code: run claude mcp add helpscout --env HELPSCOUT_APP_ID=... --env HELPSCOUT_APP_SECRET=... -- npx -y help-scout-mcp-server. 2c. Other MCP clients (Cursor, VS Code, etc.): add npx [email protected] with the env vars to your mcpServers config. 2d. Docker: docker run with HELPSCOUT_APP_ID and HELPSCOUT_APP_SECRET env vars. Optionally set HELPSCOUT_DOCS_API_KEY for Docs tools and HELPSCOUT_ENABLE_WRITES=true for writes.
claude_desktop_config.json
{"mcpServers":{"helpscout":{"command":"npx","args":["[email protected]"],"env":{"HELPSCOUT_APP_ID":"your-app-id","HELPSCOUT_APP_SECRET":"your-app-secret","HELPSCOUT_DOCS_API_KEY":"optional-docs-api-key"}}}}

Shown for Claude Desktop. Other clients may use a different file or key (VS Code uses "servers") — the configurator below converts it.

.vscode/mcp.json
{
  "servers": {
    "helpscout": {
      "command": "npx",
      "args": [
        "[email protected]"
      ],
      "env": {
        "HELPSCOUT_APP_ID": "your-app-id",
        "HELPSCOUT_APP_SECRET": "your-app-secret",
        "HELPSCOUT_DOCS_API_KEY": "optional-docs-api-key"
      }
    }
  }
}

Goes in your project's .vscode/mcp.json (VS Code uses a "servers" key).

Terminal
claude mcp add helpscout -e HELPSCOUT_APP_ID=your-app-id -e HELPSCOUT_APP_SECRET=your-app-secret -e HELPSCOUT_DOCS_API_KEY=optional-docs-api-key -- npx [email protected]

Run it in a terminal; replace any <…> placeholders with your own values first.

Check that it works

Check that search_help_scout, describe_help_scout, and read_help_scout appear in the client's tool list; then run searchConversations via read_help_scout — returned conversations confirm the connection works.

Troubleshooting

  1. Authentication failed: verify credentials with curl against api.helpscout.net/v2/oauth2/token
  2. Empty search results: searchConversations is the single search tool (use contentTerms/subjectTerms for keywords); check inbox IDs from server instructions rather than guessing; broaden terms or time range
  3. Tools missing in Cowork: update the desktop app to the latest version and start a fresh session
  4. Need more detail: run with LOG_LEVEL=debug

Things to try

Once connected, you can ask your AI assistant things like:

  • Show me active tickets from this week
  • Find conversations about billing errors
  • Find customer [email protected]
  • Show support history for organization 456

Tools 4

search_help_scout read-only
Find Help Scout operations by intent (e.g., 'customer conversation history', 'happiness report').
describe_help_scout read-only
Load the full input schemas for the operations you selected.
read_help_scout read-only
Execute one operation, e.g., getThreads, searchConversations, searchCustomersByEmail, and other read operations.
write_help_scout writes
Optional write tool (operator-enabled) carrying 11 tier-1 conversation operations; customer-visible operations (sendReply, publishDraft) need an extra flag plus explicit confirmation.

Use cases

Search conversations by keyword, status, tag, email domain, or ticket number
Look up customers by name or email and pull contact channels
Inspect organizations, their members, and support history
Pull full thread history before drafting a reply
Search and retrieve Docs knowledge base articles
Pull reports and metadata (company, channels, productivity, happiness, users, teams)
Monitor inbox activity across multiple inboxes with optional redaction

Supported clients

Claude Desktop
Claude Code
Cursor
VS Code
Windsurf
Continue
Goose
Claude Cowork
Codex
Gemini CLI
OpenCode

Listed from the project's documentation, not tested by this site.

Overview

An MCP server for Help Scout that gives AI assistants direct access to inboxes, conversations, customers, organizations, threads, and the Docs knowledge base, with full read coverage (55 operations across the Mailbox and Docs APIs) plus opt-in writes (draft replies, internal notes, tags, status, assignment, snooze) that are off by default. It keeps the advertised tool surface compact via a three-tool gateway (search/describe/read) and supports message content redaction and scoped inbox access. Auth uses Help Scout OAuth2 Client Credentials; MIT licensed; installable via npm (npx), Docker, or a Claude Desktop extension (.mcpb).

Similar servers

BioMCP 75 · B

One binary. One grammar. Evidence from the biomedical sources you already trust.

★ 659 · Tools 11 Compare with this →

Source revision 56c3434ef079 Data synced 2026-10-19 Read the FMRS scoring method