drewburchfield/help-scout-mcp-server

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.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

Prerequisites

• Node.js 18+ (for command line usage)
• Help Scout Account with API access
• OAuth2 App or Personal Access Token from Help Scout
• Claude Desktop (for DXT installation) or any MCP-compatible client

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

Quick Start

🎯 Option 1: Claude Desktop (DXT One-Click Install)

Easiest setup using DXT (Desktop Extensions) - no configuration needed:

1. Download the latest .dxt file from releases
2. Double-click to install in Claude Desktop
3. Enter your Help Scout OAuth2 Client ID and Client Secret when prompted
4. Start using immediately!

📋 Option 2: Claude Desktop (Manual Config)

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

🐳 Option 3: Docker

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

💻 Option 4: Command Line

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

Getting Your API Credentials

🎯 Recommended: OAuth2 Client Credentials

1. Go to Help Scout → My Apps → Create Private App
2. Fill in app details and select required scopes
3. Copy your Client ID and Client Secret
4. Use in configuration:
   • HELPSCOUT_CLIENT_ID=your-client-id
   • HELPSCOUT_CLIENT_SECRET=your-client-secret

🔐 Alternative: Personal Access Token

1. Go to Help Scout → Your Profile → API Keys
2. Create a new Personal Access Token
3. Use in configuration: HELPSCOUT_API_KEY=Bearer your-token-here

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

Core Search Tools

Analysis & Retrieval Tools

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 DXT manifest.

Search Examples

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

Listing Recent Conversations

// Best for "show me recent tickets" - omit query parameter
searchConversations({
  status: "active",
  limit: 25,
  sort: "createdAt",
  order: "desc"
})

Content-Based Search

// Best for "find tickets about X" - requires search terms
comprehensiveConversationSearch({
  searchTerms: ["urgent", "billing"],
  timeframeDays: 60,
  inboxId: "256809"
})

Content-Specific Searches

// Search in message bodies and subjects
comprehensiveConversationSearch({
  searchTerms: ["refund", "cancellation"],
  searchIn: ["both"],
  timeframeDays: 30
})

// Customer organization search
advancedConversationSearch({
  emailDomain: "company.com",
  contentTerms: ["integration", "API"],
  status: "active"
})

Help Scout Query Syntax

// Advanced query syntax support
searchConversations({
  query: "(body:\"urgent\" OR subject:\"emergency\") AND tag:\"escalated\"",
  status: "active"
})

Configuration Options

Compatibility

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

• 🖥️ Desktop Applications: Claude Desktop, AI coding assistants, and other MCP-enabled desktop apps
• 📝 Code Editors: VS Code extensions, Cursor, and other editors with MCP support
• 🔌 Custom Integrations: Any application implementing the MCP standard
• 🛠️ Development Tools: Command-line MCP clients and custom automation scripts

Primary Platform: Claude Desktop with full DXT and manual configuration support

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

Security & Privacy

• 🔒 PII Protection: Message content redacted by default
• 🛡️ Secure Authentication: OAuth2 Client Credentials or Personal Access Token with automatic refresh
• 📝 Audit Logging: Comprehensive request tracking and error logging
• ⚡ Rate Limiting: Built-in retry logic with exponential backoff
• 🏢 Enterprise Ready: SOC2 compliant deployment options

Development

# Quick start
git clone https://github.com/drewburchfield/help-scout-mcp-server.git
cd help-scout-mcp-server
npm install && npm run build

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

# Start the server
npm start

Troubleshooting

Common Issues

Authentication Failed

# Verify your credentials
echo $HELPSCOUT_CLIENT_ID
echo $HELPSCOUT_CLIENT_SECRET

# Test with curl
curl -X POST https://api.helpscout.net/v2/oauth2/token \
  -d "grant_type=client_credentials&client_id=$HELPSCOUT_CLIENT_ID&client_secret=$HELPSCOUT_CLIENT_SECRET"

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
• Verify inbox permissions with your API credentials
• Check conversation exists and you have access
• Try broader search terms or different time ranges

Debug Mode

Enable debug logging to troubleshoot issues:

LOG_LEVEL=debug npx help-scout-mcp-server

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

We welcome contributions! Here's how to get started:

🚀 Quick Development Setup

git clone https://github.com/drewburchfield/help-scout-mcp-server.git
cd help-scout-mcp-server
npm install

🔧 Development Workflow

# Run tests
npm test

# Type checking
npm run type-check

# Linting
npm run lint

# Build for development
npm run build

# Start development server
npm run dev

📋 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
• Authentication method (OAuth2/Personal Access Token)
• 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

License

MIT License - see file for details.

Need help? Open an issue or check our documentation.