v1.7.0: Customer & Organization Intelligence

What's New

Customer Lookup

Look up any customer by name, email, or advanced query. Get their full profile with contact details, or search by exact email using the v3 API with cursor pagination.

• listCustomers - Browse and search customers
• searchCustomersByEmail - Find a customer by email address
• getCustomer - Full customer profile with embedded contacts and address
• getCustomerContacts - All contact channels (emails, phones, chats, social profiles, websites, address)

Organization Traversal

Explore organizations and traverse the full relationship graph: org to members to their conversations.

• listOrganizations - Browse organizations sorted by activity, name, or size
• getOrganization - Organization profile with customer and conversation counts
• getOrganizationMembers - Everyone in an organization
• getOrganizationConversations - Complete support history for an organization

Workflow Examples

Customer investigation: searchCustomersByEmail -> getCustomer -> getCustomerContacts -> structuredConversationFilter -> getThreads

Account review: listOrganizations -> getOrganization -> getOrganizationMembers -> getOrganizationConversations

Improvements

• Expanded PII redaction coverage across all customer and organization output paths
• Improved rate limit handling with proper retry behavior
• Better input validation with stricter schema checks
• Inbox cache now persists for 24 hours (previously refreshed too frequently)
• MCP SDK upgraded to 1.27.1

Install

npm install help-scout-mcp-server@1.7.0

Or download the .mcpb file below for Claude Desktop one-click install.

Full Changelog: v1.6.2...v1.7.0

v1.6.2

What's Changed

Bug Fixes

• Fix date filtering: Replace modifiedSince API param with createdAt query syntax across all search tools. createdAfter now correctly filters by creation date, not modification date.
• Fix status defaults: advancedConversationSearch and structuredConversationFilter now default to status=all instead of silently searching only active conversations.
• Add date validation: ISO 8601 format validation on date inputs prevents query injection and strips milliseconds.

Tools Affected

• searchConversations
• comprehensiveConversationSearch
• advancedConversationSearch
• structuredConversationFilter

Install

npm install help-scout-mcp-server@1.6.2

Or download the .mcpb file below for Claude Desktop one-click install.

Full Changelog: v1.6.1...v1.6.2

v1.6.1

What's New in v1.6.1

Bug Fixes

• Pagination Bug Fix: Multi-status searches now report accurate total counts. Previously, searching without a status filter (active/pending/closed in parallel) reported totalResults capped at the page limit instead of the real total across all statuses. Now returns totalAvailable (sum of API totals) and totalByStatus breakdown. (#10)

Improvements

• Client-Side Date Filtering: New createdBefore parameter for all search tools with clear metadata distinguishing filtered counts from API totals
• Partial Failure Transparency: Multi-status searches now surface structured error info when individual status queries fail, instead of silently returning incomplete results
• Stronger Error Type Guard: isApiError now validates against the schema enum, preventing false matches on Node.js system errors

Security

• Upgraded @modelcontextprotocol/sdk to 1.26.0
• Fixed vulnerabilities in axios, hono, and qs transitive dependencies

Installation

• Claude Desktop: Download help-scout-mcp-server-1.6.1.mcpb below and double-click to install
• npm: npm install help-scout-mcp-server@1.6.1
• Docker: docker pull drewburchfield/help-scout-mcp-server:1.6.1

v1.6.0: Inbox Auto-Discovery & MCP Tool Search Optimization

What's New

🔍 Inbox Auto-Discovery

• Inboxes are now automatically discovered on server connect
• Inbox IDs included directly in server instructions
• No more manual inbox lookups needed

⚡ MCP Tool Search Optimization

• Shorter tool descriptions (~60% reduction)
• Streamlined argument descriptions (~62% reduction)
• Workflow table in server instructions for better tool selection
• Added structuredConversationFilter tool for ticket number lookups

🛠️ Improvements

• Async factory pattern: HelpScoutMCPServer.create()
• Multi-status search with Promise.allSettled
• Better error handling for inbox discovery failures

Installation

npm install help-scout-mcp-server

Or use the MCPB extension (attached) for one-click Claude Desktop installation.

v1.5.0 - MCP SDK Upgrade, Security Improvements & New Tools

What's New

🔧 Core Improvements

• MCP SDK v1.25.2: Latest Model Context Protocol SDK with enhanced compatibility
• Auth Alignment: Standardized environment variable naming (HELPSCOUT_APP_ID/HELPSCOUT_APP_SECRET) to match Help Scout UI
• Content Redaction: Renamed to REDACT_MESSAGE_CONTENT for clarity

🆕 New Tool

• structuredConversationFilter: ID-based refinement and direct ticket number lookup (e.g., "Show ticket #42839")

🛡️ Security & Stability

• CI Branch Guard: Docker builds now verify tag is on main branch before publishing
• Enhanced Input Validation: Improved error handling from comprehensive code review
• Tool Discovery: Clearer descriptions and decision tree for better LLM tool selection

📦 Installation

NPM (Claude Code, Cursor, etc.):
```bash
npx help-scout-mcp-server
```

Docker:
```bash
docker run -e HELPSCOUT_APP_ID="your-id" -e HELPSCOUT_APP_SECRET="your-secret" drewburchfield/help-scout-mcp-server
```

Claude Desktop: Download the .mcpb file below and double-click to install.

Configuration

```
HELPSCOUT_APP_ID=your-app-id
HELPSCOUT_APP_SECRET=your-app-secret
```

See README for full documentation.

v1.3.0 - MCP SDK Upgrade & Enhanced Tool Guidance

🎉 What's New in v1.3.0

• 🆙 MCP SDK v1.17.4: Latest Model Context Protocol SDK with enhanced compatibility
• 🎯 DXT Format Compliance: Fixed manifest format to follow official Anthropic specification
• 📝 Enhanced Tool Guidance: Clear distinction between listing (searchConversations) vs content-based searches (comprehensiveConversationSearch)
• 🔧 Improved Search UX: Better tool descriptions prevent empty search term confusion
• 🛠️ Enhanced Version Management: Automated version bump script for all 6 version-sensitive files
• ✅ Test Reliability: Fixed async test handling and improved timeout management
• 🔒 Production Ready: Complete release workflow with DXT building and GitHub releases

📦 Installation Options

🎯 Claude Desktop (One-Click DXT)

1. Download helpscout-mcp-extension.dxt below
2. Double-click to install in Claude Desktop
3. Enter Help Scout OAuth2 credentials
4. Start using immediately!

📋 Manual NPM Installation

npx help-scout-mcp-server@1.3.0

🐳 Docker

docker pull drewburchfield/help-scout-mcp-server:1.3.0

🔧 Key Improvements

This release specifically addresses tool selection confusion by making it crystal clear:

• Use searchConversations (without query) for "show me recent tickets"
• Use comprehensiveConversationSearch (with search terms) for "find tickets about billing"

Assets

• NPM Package: help-scout-mcp-server@1.3.0
• Docker Image: drewburchfield/help-scout-mcp-server:1.3.0
• DXT Extension: helpscout-mcp-extension.dxt (attached below)

v1.2.1 - DXT Documentation Update

🔗 DXT Enhancement Release

Minor update to improve the DXT extension experience:

✨ What's New

• 📚 Documentation Link: DXT now includes direct link to README documentation
• 🎨 Icon Fix: Corrected icon reference in DXT manifest

🎯 DXT Installation

Download the .dxt file below and double-click to install in Claude Desktop:

• One-click installation with OAuth2 credential setup
• Automatic updates when new versions are released
• No Node.js installation required

📦 Installation Options

• 🎯 DXT Extension: Download .dxt file for Claude Desktop
• 💻 Command Line: npx help-scout-mcp-server
• 🐳 Docker: docker run drewburchfield/help-scout-mcp-server

🔄 Auto-Update Test

This release tests the DXT auto-update mechanism in Claude Desktop. Existing DXT users should receive an automatic update notification.

v1.2.0: DXT Extension for One-Click Claude Desktop Installation

🎯 Major Feature: DXT Extension

The biggest addition in v1.2.0 is the DXT (Desktop Extensions) package for one-click installation in Claude Desktop, eliminating the need for manual Node.js setup and configuration.

✅ DXT Benefits:

• One-click installation in Claude Desktop
• Bundled dependencies (no Node.js setup required)
• Secure credential storage in OS keychain/Credential Manager
• User-friendly configuration UI
• Cross-platform support (macOS, Windows, Linux)

🚀 Other New Features

• Dependency injection with ServiceContainer for better code organization
• HTTP connection pooling for improved performance
• Reverse logic validation system for Help Scout API constraints
• Enhanced conversation search with multi-status support

🔧 Technical Improvements

• Windows compatibility for DXT extension builds
• Comprehensive test coverage with integration tests
• Security fixes addressing Semgrep findings
• Improved error handling with MCP-compliant responses
• Connection reuse and performance optimizations

📦 Installation Options

🎉 Recommended: Claude Desktop (DXT Extension)

Download the .dxt file below and install in Claude Desktop for the easiest setup experience.

NPM Package

npm install -g help-scout-mcp-server@1.2.0

Docker

docker pull help-scout-mcp-server:1.2.0

🔗 Links

• NPM Package
• Documentation