A comprehensive Model Context Protocol (MCP) server for HelpScout's Mailbox API v2. This server provides 47+ tools and 18 interactive MCP apps for complete customer support management.

Features

🛠️ Tools (47)

Conversations (12 tools)

List, get, create, update, delete conversations
Manage threads (list, create reply, create note, create phone)
Update tags, change status, assign conversations

Customers (12 tools)

List, get, create, update, delete customers
Manage customer emails, phones, addresses
List customer properties

Mailboxes (5 tools)

List and get mailboxes
List folders and custom fields

Users (3 tools)

List and get users
Get current authenticated user

Tags (4 tools)

List, create, update, delete tags

Workflows (5 tools)

List, get workflows
Activate/deactivate workflows
Get workflow statistics

Saved Replies (5 tools)

List, get, create, update, delete saved replies

Teams (3 tools)

List, get teams
List team members

Webhooks (5 tools)

List, get, create, update, delete webhooks

Reporting (5 tools)

Company overview report
Conversations report
Happiness report
Productivity report
User-specific reports

📱 MCP Apps (18)

conversation-dashboard - Dashboard view of conversations with filters
conversation-detail - Detailed single conversation view
conversation-grid - Card-based grid layout
conversation-timeline - Visual timeline of conversation history
customer-grid - Grid view of all customers
customer-detail - Detailed customer profile
mailbox-overview - Overview of all mailboxes
folder-browser - Browse and manage folders
user-stats - Individual user performance metrics
tag-manager - Manage tags with usage stats
workflow-dashboard - Workflow management dashboard
workflow-detail - Detailed workflow configuration
saved-replies - Browse and manage saved replies
team-overview - Team structure and member stats
happiness-report - Customer satisfaction metrics
productivity-report - Team productivity metrics
company-report - Overall company performance KPIs
search-results - Search interface for conversations

Installation

npm install
npm run build

Configuration

Create a .env file with your HelpScout credentials:

HELPSCOUT_APP_ID=your_app_id
HELPSCOUT_APP_SECRET=your_app_secret

Getting HelpScout Credentials

Go to https://secure.helpscout.net/apps/
Create a new app
Copy the App ID and App Secret
Add them to your .env file

Usage

With MCP Client

Add to your MCP client configuration:

{
  "mcpServers": {
    "helpscout": {
      "command": "node",
      "args": ["/path/to/helpscout/dist/main.js"],
      "env": {
        "HELPSCOUT_APP_ID": "your_app_id",
        "HELPSCOUT_APP_SECRET": "your_app_secret"
      }
    }
  }
}

Standalone

npm start

API Coverage

This server implements the HelpScout Mailbox API v2:

Base URL: https://api.helpscout.net/v2/
Authentication: OAuth2 Client Credentials
Features: Pagination, error handling, automatic token refresh

Tool Examples

List Active Conversations

{
  "name": "helpscout_list_conversations",
  "arguments": {
    "status": "active",
    "mailbox": 123456
  }
}

Create a Conversation

{
  "name": "helpscout_create_conversation",
  "arguments": {
    "subject": "Need help with billing",
    "type": "email",
    "mailboxId": 123456,
    "customerEmail": "customer@example.com",
    "status": "active"
  }
}

Get Happiness Report

{
  "name": "helpscout_get_happiness_report",
  "arguments": {
    "start": "2025-01-01",
    "end": "2025-01-31"
  }
}

MCP Apps Usage

Access MCP apps as resources:

helpscout://app/conversation-dashboard
helpscout://app/customer-detail
helpscout://app/happiness-report

Each app provides a rich HTML interface for interacting with HelpScout data.

Development

# Build
npm run build

# Watch mode
npm run dev

# Prepare for publishing
npm run prepare

Architecture

src/
├── api/
│   └── client.ts          # HelpScout API client with OAuth2
├── tools/
│   ├── conversations-tools.ts
│   ├── customers-tools.ts
│   ├── mailboxes-tools.ts
│   ├── users-tools.ts
│   ├── tags-tools.ts
│   ├── workflows-tools.ts
│   ├── saved-replies-tools.ts
│   ├── teams-tools.ts
│   ├── webhooks-tools.ts
│   └── reporting-tools.ts
├── apps/
│   ├── conversation-dashboard.ts
│   ├── conversation-detail.ts
│   └── ... (18 apps total)
├── types/
│   └── index.ts           # TypeScript type definitions
├── server.ts              # MCP server implementation
└── main.ts                # Entry point

Error Handling

The server includes comprehensive error handling:

API errors are caught and returned with detailed messages
Token refresh is automatic
Pagination handles large datasets gracefully

Contributing

This is part of the MCPEngine project. For contributions, please refer to the main repository guidelines.

License

MIT

README.md

HelpScout MCP Server