Help Scout MCP (GravityKit)

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.

Note: This is a fork of the original help-scout-mcp by Drew Burchfield.

📖 Table of Contents

• 🎉 What's New
• ⚡ Quick Start
• 🔑 API Credentials
• 🛠️ Tools & Capabilities
• 📋 Response Modes
• ⚙️ Configuration
• 🔍 Troubleshooting
• 🤝 Contributing

🎉 What's New

• 📚 Full Docs API Integration: Complete support for Help Scout Docs API
  • Browse and search documentation sites, collections, categories, and articles
  • Read full article content with PII protection
  • Update articles, collections, and categories (with safety controls)
• 📈 Complete Reports API: All Help Scout Reports endpoints implemented
  • Conversation reports (chat, email, phone) with detailed metrics
  • User/team performance reports with productivity analytics
  • Company-wide reports with customer and team insights
  • Happiness reports with satisfaction scores and feedback
  • Docs analytics with article views and visitor metrics
• 🎯 MCPB Extension: One-click installation for Claude Desktop
• 🔧 Clear Environment Variables: HELPSCOUT_APP_ID and HELPSCOUT_APP_SECRET
• ⚡ Connection Pooling: Improved performance with HTTP connection reuse
• 🛡️ Enhanced Security: Comprehensive input validation and API constraints
• 🔄 Dependency Injection: Cleaner architecture with ServiceContainer
• 🧪 Comprehensive Testing: 69%+ branch coverage with reliable tests

Prerequisites

• Node.js 18+ (for command line usage)
• Help Scout Account with API access
• OAuth2 App from Help Scout (Personal Access Tokens are no longer supported)
• Claude Code, Claude Desktop, or any MCP-compatible client

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

Quick Start

⚡ Option 1: Claude Code (Easiest)

The fastest way to get started — just ask Claude to install it:

claude "Install the @gravitykit/help-scout-mcp MCP server"

Claude Code will add it to your project's .mcp.json automatically. When prompted, provide your Help Scout App ID and App Secret.

You can also add it manually:

claude mcp add helpscout -- npx @gravitykit/help-scout-mcp

Then set your credentials in .mcp.json:

{
  "mcpServers": {
    "helpscout": {
      "command": "npx",
      "args": ["@gravitykit/help-scout-mcp"],
      "env": {
        "HELPSCOUT_APP_ID": "your-app-id",
        "HELPSCOUT_APP_SECRET": "your-app-secret"
      }
    }
  }
}

🎯 Option 2: Claude Desktop (MCPB One-Click Install)

Easiest setup using MCP Bundles - no configuration needed:

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

📋 Option 3: Claude Desktop (Manual Config)

{
  "mcpServers": {
    "helpscout": {
      "command": "npx",
      "args": ["@gravitykit/help-scout-mcp"],
      "env": {
        "HELPSCOUT_APP_ID": "your-app-id",
        "HELPSCOUT_APP_SECRET": "your-app-secret"
      }
    }
  }
}

💻 Option 4: Command Line

HELPSCOUT_APP_ID="your-app-id" \
HELPSCOUT_APP_SECRET="your-app-secret" \
npx @gravitykit/help-scout-mcp

Getting Your API Credentials

🎯 Recommended: OAuth2 Client Credentials (Step-by-Step)

This method is recommended for production use and provides automatic token refresh.

Why Client Credentials? MCP servers are backend applications that run without user interaction. We use the Client Credentials flow (not Authorization Code flow) because:

• ✅ No browser or user login required
• ✅ Perfect for server-to-server authentication
• ✅ Automatic token refresh
• ✅ Works with Claude Desktop, Continue.dev, etc.

Step 1: Create a Private App

1. Log in to your Help Scout account
2. Click your profile icon (top right) → My Apps
3. Click Create My App
4. Fill out the form:
   • App Name: e.g., "Help Scout MCP Server"
   • Redirection URL: Use https://example.com (required field but not used for server apps)
   • Description: Optional description of your integration

Step 2: Configure App Permissions

Select the scopes your app needs:

• ✅ Mailbox - Read conversations, threads, and mailbox data
• ✅ Customers - Access customer information
• ✅ Reports - Access analytics and reporting (Plus/Pro plans only)
• ✅ Users - Read user information
• ✅ Webhooks - If you need webhook functionality

Note: Only select the scopes you actually need for security best practices.

Step 3: Save and Get Credentials

1. Click Create Application
2. You'll see your credentials:
   • App ID (this is your Client ID)
   • App Secret (this is your Client Secret)
3. ⚠️ Important: Copy these immediately! The App Secret is only shown once.

Step 4: Configure the MCP Server

Set these environment variables:

export HELPSCOUT_APP_ID="your-app-id-here"
export HELPSCOUT_APP_SECRET="your-app-secret-here"

Or add to your .env file:

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

Step 5: Test Your Configuration

# Test with environment variables
HELPSCOUT_APP_ID="your-app-id" \
HELPSCOUT_APP_SECRET="your-app-secret" \
npx @gravitykit/help-scout-mcp

# Or if using .env file
npx @gravitykit/help-scout-mcp

Troubleshooting OAuth Issues

• "Unknown URL" for Reports: Ensure your account has a Plus/Pro plan
• Authentication Failed: Double-check your App ID and App Secret
• Missing Scopes: Go back to My Apps and edit your app's permissions
• Token Expired: The server handles refresh automatically

📚 For Docs API Access

1. Go to Help Scout Docs Settings
2. Generate a Docs API Key
3. Use in configuration: HELPSCOUT_DOCS_API_KEY=your-docs-api-key

Important Notes:

• The Docs API key is separate from your main Help Scout API credentials
• Ensure Help Scout Docs is enabled for your account
• You must have at least one Docs site created to access documentation
• Reports API (for analytics) requires Plus/Pro plan

Features

• 🔍 Advanced Search: Multi-status conversation search, content filtering, boolean queries
• 💬 Reply Creation: Draft or published replies with HTML formatting optimized for Help Scout
• 📊 Smart Analysis: Conversation summaries, thread retrieval, inbox monitoring
• 📚 Docs Integration: Full Help Scout Docs API support for articles, collections, and categories
• 📈 Comprehensive Reports: All Help Scout Reports API endpoints - chat, email, phone, user, company, happiness, and docs analytics
• 🔒 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

Conversation Tools

Documentation Tools

Set HELPSCOUT_DISABLE_DOCS=true to hide all Docs tools if you don't use Help Scout Docs.