Help Scout MCP (GravityKit) README

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.

Reports & Analytics Tools

Resources

Conversations

• 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

Documentation

• helpscout-docs://sites - List all documentation sites
• helpscout-docs://collections - List collections with filtering
• helpscout-docs://categories - List categories in a collection
• helpscout-docs://articles - Get articles with full content

Search Examples

Tip: searchConversations handles listing, keyword search, and structured search — use different parameters for different needs.

Listing Recent Conversations

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

Content-Based Search

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

Content-Specific Searches

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

// Customer organization search (structured fields)
searchConversations({
  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"
})

Documentation Examples

// List all documentation sites
listDocsSites({
  page: 1
})

// Get articles in a collection
listDocsArticles({
  collectionId: "123456",
  status: "published",
  sort: "popularity"
})

// Get full article content
getDocsArticle({
  articleId: "789012"
})

// Update an article
updateDocsArticle({
  articleId: "789012",
  name: "Updated Article Title",
  text: "<p>New article content</p>"
})

Creating Replies

// Create a draft reply (default, safe)
createReply({
  conversationId: "98234",
  text: "<p>Thanks for reaching out! Let me look into this.</p>",
  customer: { email: "maria@example.com" }
})

// Create a published reply (requires HELPSCOUT_ALLOW_SEND_REPLY=true)
createReply({
  conversationId: "98234",
  text: "<p>Your export issue has been resolved.</p>",
  customer: { id: 67890 },
  draft: false,
  status: "closed"
})

HTML in replies is automatically formatted for Help Scout's native editor:

• <p> tags converted to <br><br> line breaks
• <pre> blocks converted to <div> (Help Scout strips <pre>)
• <code> tags get class="inline-code" for styling
• Block element spacing controlled by HELPSCOUT_REPLY_SPACING

Managing Conversations

// Get a conversation by ID
getConversation({
  conversationId: "98234"
})

// Get a conversation with embedded threads
getConversation({
  conversationId: "98234",
  embed: ["threads"]
})

// Create a new conversation
createConversation({
  subject: "New support request",
  type: "email",
  mailboxId: 256809,
  customer: { email: "maria@example.com" },
  threads: [{ type: "customer", text: "I need help with my account." }]
})

// Update a conversation's status and tags
updateConversation({
  conversationId: "98234",
  status: "pending",
  tags: ["billing", "priority"]
})

// Reassign a conversation
updateConversation({
  conversationId: "98234",
  assignTo: 12345
})

Summarizing Tickets with Transcripts

// Single call: get latest tickets with full message transcripts
searchConversations({
  includeTranscripts: true,
  limit: 10
})

// Search with transcripts for AI analysis
searchConversations({
  searchTerms: ["billing", "refund"],
  includeTranscripts: true,
  transcriptMaxMessages: 5
})

Reports Examples

// Get email conversation report with comparison
getReport({
  type: "email",
  start: "2024-01-01T00:00:00Z",
  end: "2024-01-31T23:59:59Z",
  previousStart: "2023-12-01T00:00:00Z",
  previousEnd: "2023-12-31T23:59:59Z",
  mailboxes: ["123456"],
  viewBy: "week"
})

// Get user performance report
getReport({
  type: "user",
  start: "2024-01-01T00:00:00Z",
  end: "2024-01-31T23:59:59Z",
  user: "789012",
  types: ["email", "chat"],
  officeHours: true
})

// Get happiness report with filters
getReport({
  type: "happiness",
  start: "2024-01-01T00:00:00Z",
  end: "2024-01-31T23:59:59Z",
  rating: ["great", "ok"],
  mailboxes: ["123456"],
  viewBy: "day"
})

// Get company-wide analytics
getReport({
  type: "company",
  start: "2024-01-01T00:00:00Z",
  end: "2024-01-31T23:59:59Z",
  viewBy: "month"
})

Response Modes

The server provides three response modes to optimize token usage and support different use cases.

Slim (default)

Every conversation and thread is stripped to just the fields that matter: id, number, subject, status, preview, assignee, customer, tags, and dates. All Help Scout API cruft (_links, _embedded, closedByUser, source metadata, tag styles, photo URLs, etc.) is removed automatically.

{
  "id": 98234,
  "number": 14052,
  "subject": "Can't export to CSV",
  "status": "active",
  "preview": "When I click Export, nothing happens...",
  "assignee": { "first": "Rafael", "last": "Smith" },
  "customer": { "first": "Maria", "last": "Garcia", "email": "maria@example.com" },
  "tags": ["tech-support"],
  "createdAt": "2026-02-14T10:30:00Z"
}

Verbose (verbose: true)

Returns the full, raw Help Scout API response objects. Useful for debugging or when you need a specific field that slim mode strips out. This behavior is still supported, but verbose is no longer advertised in tool schemas; the default public surface stays slim.

{
  "id": 98234,
  "number": 14052,
  "subject": "Can't export to CSV",
  "status": "active",
  "state": "published",
  "type": "email",
  "preview": "When I click Export, nothing happens...",
  "mailboxId": 256809,
  "assignee": { "id": 12345, "first": "Rafael", "last": "Smith", "email": "rafael@company.com" },
  "createdBy": { "id": 67890, "type": "customer" },
  "customer": { "id": 67890, "first": "Maria", "last": "Garcia", "email": "maria@example.com" },
  "tags": [{ "id": 13974028, "name": "tech-support", "color": "#929292" }],
  "closedBy": null,
  "closedByUser": null,
  "source": { "type": "email", "via": "customer" },
  "_links": { "self": { "href": "..." }, "threads": { "href": "..." }, "mailbox": { "href": "..." } },
  "_embedded": { "threads": { "_links": { "..." } } }
}

Transcript

Purpose-built for AI analysis and summarization. Available in two ways:

• Single conversation: getThreads with format: "transcript"
• Batch with search: searchConversations with includeTranscripts: true

Transcripts:

• Exclude AI-generated drafts (source.type: "support-agent-ai") and unsent drafts (state: "draft") by default. Set excludeDrafts: false on getThreads to include all threads.
• Include only customer/staff messages (strips internal notes, line items, system events)
• Sort chronologically (oldest first, natural reading order)
• Strip all HTML to plain text
• Clean up Help Scout Beacon form HTML (extracts the actual message from form markup)
• Respect the REDACT_MESSAGE_CONTENT privacy setting
• Cap message count per conversation (transcriptMaxMessages, default 10)

Inline Transcripts on Search

Before — summarizing 10 tickets required 11 API calls:

// 1. Search for conversations
const results = searchConversations({ limit: 10 })

// 2. Fetch threads for each conversation individually
for (const conversation of results) {
  getThreads({ conversationId: conversation.id, format: "transcript" })
}

After — a single call:

searchConversations({ includeTranscripts: true, limit: 10 })

Returns conversations with inline transcript arrays:

{
  "results": [
    {
      "id": 98234,
      "subject": "Can't export to CSV",
      "status": "active",
      "customer": { "first": "Maria" },
      "transcript": [
        { "role": "customer", "from": "Maria", "date": "...", "body": "When I click Export, nothing happens..." },
        { "role": "staff", "from": "Rafael", "date": "...", "body": "Could you try disabling your browser extensions?" }
      ]
    }
  ],
  "includeTranscripts": true,
  "transcriptMaxMessages": 10
}

Design notes:

• When includeTranscripts is true and no limit is specified, defaults to 10 conversations (not 50)
• Thread requests fire concurrently via Promise.allSettled — one failed transcript doesn't break the response
• If a transcript fetch fails, the conversation still appears with transcript: null and a transcriptError field
• The transcript format is identical whether fetched via getThreads or searchConversations

Configuration Options

Smart Site & Collection Resolution

The MCP server includes intelligent natural language processing for Help Scout Docs sites and collections:

Natural Language Queries

Collections

// These all work to find GravityKit articles:
listDocsCollections({ query: "GravityKit" })
getSiteCollections({ query: "GravityKit" })
searchDocsArticles({ query: "GravityKit help articles" })

Sites

// Natural language site queries:
listDocsCollections({ query: "GravityKit" })  // Find GravityKit site
getSiteCollections({ query: "TrustedLogin site" })  // Get TrustedLogin collections
listDocsSites({ query: "gravity" })  // Find sites matching "gravity"

Matching Algorithm

The system matches sites and collections using:

1. Direct name match - Exact site/collection name (100% confidence)
2. Company/Site name match - Company name like "GravityKit" (80-90% confidence)
3. Subdomain match - Matches subdomain patterns (70-80% confidence)
4. CNAME match - Custom domain matching (70% confidence)
5. Partial word match - Intelligent fuzzy matching (variable confidence)

Default Configuration

Set default site and collection for queries without specific context:

export HELPSCOUT_DEFAULT_DOCS_SITE_ID="your-site-id"
export HELPSCOUT_DEFAULT_DOCS_COLLECTION_ID="your-collection-id"

Discovery Tools

• Use listDocsSites to see all Docs sites (with optional NLP filtering)
• Use getSiteCollections to get collections for a specific site using NLP
• Sites and collections are automatically cached for performance

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 MCPB 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: Optional message content redaction via REDACT_MESSAGE_CONTENT
• 🛡️ 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

Changelog

See GitHub Releases for version history and release notes.

Development

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

# Create .env file with your credentials (OAuth2)
echo "HELPSCOUT_APP_ID=your-app-id" > .env
echo "HELPSCOUT_APP_SECRET=your-app-secret" >> .env

# Start the server
npm start

Troubleshooting

Common Issues

Authentication Failed

# Verify your credentials
echo $HELPSCOUT_APP_ID
echo $HELPSCOUT_APP_SECRET

# Test with curl
curl -X POST https://api.helpscout.net/v2/oauth2/token \
  -d "grant_type=client_credentials&client_id=$HELPSCOUT_APP_ID&client_secret=$HELPSCOUT_APP_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

• Use searchConversations without searchTerms for listing, with searchTerms for keyword search
• Don't use empty strings [""] in searchTerms
• Verify inbox permissions with your API credentials
• Check conversation exists and you have access
• Try broader search terms or different time ranges

Reports API "Unknown URL" Errors

If you're getting "Unknown URL" errors when accessing reports:

1. Verify Your Plan

• Reports API requires a Plus or Pro plan
• Standard plan users can purchase Reports as an add-on
• Check your plan: Help Scout → Manage → Account → Billing

2. Check OAuth App Permissions

• Go to My Apps → Edit your app
• Ensure Reports scope is selected
• Save and regenerate credentials if needed

3. Feature Availability

• Happiness Reports: Requires happiness ratings to be enabled
  • Go to: Manage → Company → Email → Happiness Ratings
• Chat/Phone Reports: Only available if these channels are enabled
• Docs Reports: Requires Help Scout Docs to be enabled

4. API Response Debugging

# Enable debug logging to see actual API responses
LOG_LEVEL=debug npx @gravitykit/help-scout-mcp

Debug Mode

Enable debug logging to troubleshoot issues:

LOG_LEVEL=debug npx @gravitykit/help-scout-mcp

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/GravityKit/help-scout-mcp.git
cd help-scout-mcp
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 used
• 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: @gravitykit/help-scout-mcp

License

MIT License - see LICENSE file for details.

Need help? Open an issue or check our documentation.