Help Scout MCP Server

Help Scout MCP Server - Connect Claude and other AI assistants to your Help Scout data with enterprise-grade security and advanced search capabilities.

Table of Contents

• What's New

• Quick Start

• API Credentials

• Tools & Capabilities

• Configuration

• Troubleshooting

• Contributing

What's New in v1.6.0

• Inbox Auto-Discovery: Inboxes automatically discovered on server connect and included in server instructions—no need to call searchInboxes first

• Multi-Status Search Default: searchConversations now searches all statuses (active, pending, closed) by default when no status specified

• Simpler Workflow: AI agents can use inbox IDs directly from server instructions without a preliminary lookup step

• Deprecated Tools: searchInboxes and listAllInboxes remain functional but are deprecated (inboxes now in instructions)

Previous Release (v1.5.0)

• MCP SDK v1.25.2 with enhanced compatibility

• structuredConversationFilter for ID-based refinement and ticket number lookup

• Enhanced input validation and error handling

• Standardized environment variable naming (APP_ID/APP_SECRET)

Migration from v1.5.0

For programmatic users:

• HelpScoutMCPServer now uses an async factory pattern: use await HelpScoutMCPServer.create() instead of new HelpScoutMCPServer()

Response format change:

• searchConversations response now includes statusesSearched array instead of status string when searching without a specific status filter

No action required for most users - the MCP protocol interface remains unchanged.

Prerequisites

• Node.js 18+ (for command line usage)

• Help Scout Account with API access

• OAuth2 App from Help Scout (App ID and App Secret)

• Claude Desktop (for extension installation) or any MCP-compatible client

Note: The desktop extension bundles Node.js, so no local installation needed for Claude Desktop users.

Quick Start

Option 1: Claude Desktop (One-Click Install)

Easiest setup using Desktop Extensions - no configuration needed:

1. Download the latest .mcpb

2. Double-click to install (or drag into Claude Desktop window)

3. Enter your Help Scout App ID and App Secret when prompted

4. Start using immediately

Option 2: JSON Config (Claude Desktop, Cursor, etc.)

Add to your MCP client's config file (e.g., claude_desktop_config.json):

Option 3: Docker

Option 4: Command Line (Claude Code, Codex, etc.)

Getting Your API Credentials

OAuth2 Client Credentials (Only Supported Method)

1. Go to Help Scout → My Apps → Create Private App

2. Fill in app details and select required scopes:

   • At minimum: Read access to Mailboxes and Conversations

3. Copy your credentials from the Help Scout UI

4. Use in configuration as shown below

Note: Help Scout API uses OAuth2 Client Credentials flow exclusively. Personal Access Tokens are not supported.

Credential Terminology

Environment variables match Help Scout's UI exactly:

Alternative variable names (also supported):

• HELPSCOUT_CLIENT_ID / HELPSCOUT_CLIENT_SECRET (OAuth2 standard naming)

• HELPSCOUT_API_KEY (legacy)

Features

• Advanced Search: Multi-status conversation search, content filtering, boolean queries

• Smart Analysis: Conversation summaries, thread retrieval, inbox monitoring

• Enterprise Security: PII redaction, secure token handling, comprehensive audit logs

• High Performance: Built-in caching, rate limiting, automatic retry logic

• Easy Integration: Works with Claude Desktop, Cursor, Continue.dev, and more

Tools & Capabilities

Quick Guide: Which tool should I use?

• Listing tickets: searchConversations - No keywords needed, great for "show recent/closed/active tickets"

• Finding by keyword: comprehensiveConversationSearch - Searches content for specific words

• Lookup ticket #: structuredConversationFilter - Direct ticket number lookup

• Complex filters: advancedConversationSearch - Email domains, tag combinations

Core Search Tools

Analysis & Retrieval Tools

Inbox Auto-Discovery (v1.6.0+)

When the server connects, it automatically discovers all available inboxes and includes them in the server instructions. AI agents can reference inbox IDs directly without calling lookup tools first.

Example server instructions snippet:

Resources (Dynamic Discovery)

• helpscout://inboxes - List all accessible inboxes

• helpscout://conversations - Search conversations with filters

• helpscout://threads - Get thread messages for a conversation

• helpscout://clock - Current server timestamp

Note: Resources are discovered dynamically at runtime through MCP protocol, not declared in the extension manifest.

Search Examples

Key Distinction: Use searchConversations (without query) for listing conversations, use comprehensiveConversationSearch (with search terms) for finding specific content.

v1.6.0+: When no status is specified, searches automatically include all statuses (active, pending, closed).

Listing Recent Conversations

Content-Based Search

Content-Specific Searches

Help Scout Query Syntax

Configuration Options

Legacy variables

Compatibility

Works with any Model Context Protocol (MCP) compatible client:

• AI Assistants: Claude Desktop, Goose, and other MCP-enabled assistants

• Code Editors: Cursor, VS Code (via extensions), Windsurf, and other editors with MCP support

• Command Line: Claude Code, Codex, Gemini CLI, OpenCode, and other CLI-based MCP clients

• Custom Integrations: Any application implementing the MCP standard

Quickest Setup: Claude Desktop with one-click extension installation - no configuration needed.

Since this server follows the MCP standard, it automatically works with any current or future MCP-compatible client.

Security & Privacy

• Content Redaction: Optional message body hiding (set REDACT_MESSAGE_CONTENT=true)

• Secure Authentication: OAuth2 Client Credentials with automatic token refresh

• Audit Logging: Comprehensive request tracking and error logging

• Rate Limiting: Built-in retry logic with exponential backoff

• Smart Inbox Scoping: Optional default inbox configuration for improved LLM context

• Enterprise Ready: SOC2 compliant deployment options

Development

Troubleshooting

Common Issues

Authentication Failed

Connection Timeouts

• Check your network connection to api.helpscout.net

• Verify no firewall blocking HTTPS traffic

• Consider increasing HTTP_SOCKET_TIMEOUT environment variable

Rate Limiting

• The server automatically handles rate limits with exponential backoff

• Reduce concurrent requests if you see frequent 429 errors

• Monitor logs for retry patterns

Empty Search Results

• Wrong tool choice: Use searchConversations (no query) for listing, comprehensiveConversationSearch for content search

• Empty search terms: Don't use empty strings [""] with comprehensiveConversationSearch

• Inbox ID issues: Use inbox IDs from server instructions (auto-discovered on connect), not guessed values

• Verify inbox permissions with your API credentials

• Check conversation exists and you have access

• Try broader search terms or different time ranges

v1.6.0+: Searches now include all statuses by default. If you're still getting empty results, verify the inbox ID matches one from the server instructions.

Debug Mode

Enable debug logging to troubleshoot issues:

Getting Help

If you're still having issues:

1. Check existing issues

2. Enable debug logging and share relevant logs

3. Include your configuration (without credentials!)

Contributing

Contributions welcome! Here's how to get started:

Development Setup

Development Workflow

Before Submitting

• All tests pass (npm test)

• Type checking passes (npm run type-check)

• Linting passes (npm run lint)

• Add tests for new features

• Update documentation if needed

Bug Reports

When reporting bugs, please include:

• Help Scout MCP Server version

• Node.js version

• App ID (not the secret!)

• Error messages and logs

• Steps to reproduce

Feature Requests

We'd love to hear your ideas! Please open an issue describing:

• The problem you're trying to solve

• Your proposed solution

• Any alternative approaches you've considered

Support

• Issues: GitHub Issues

• Discussions: GitHub Discussions

• NPM Package: help-scout-mcp-server

About This Project

Built with care by a Help Scout customer who wanted to give his support team superpowers. If you're using Help Scout and want your AI assistants to help you find conversations, spot patterns, and get context faster, this is for you.

License

MIT License - see LICENSE file for details.

Need help? Open an issue or check our documentation.