jake/help-scout-mcp-2026-complete

Jake Shore 9c05a729d5 Rebrand MCPEngine → MCPEngage + add support-specific content and OAuth details

2026-02-02 06:59:36 -05:00

6.7 KiB

Raw Permalink Blame History

🚀 Don't want to self-host? Join the waitlist for our fully managed solution →

Zero setup. Zero maintenance. Just connect and automate.

🚀 Help Scout MCP Server — 2026 Complete Version

💡 What This Unlocks

This MCP server gives AI direct access to your entire Help Scout workspace. Instead of clicking through interfaces, you just tell it what you need.

🎯 Customer Support Power Moves with Help Scout

The AI can directly control your Help Scout account with natural language:

Smart Triage — "Find all open conversations tagged 'urgent' or 'billing' from the last 24 hours, summarize each issue, and suggest priority order"
Customer Intelligence — "Pull Sarah Johnson's conversation history, identify recurring issues, check response times, and generate a support quality report"
Automated Responses — "Search for conversations about 'password reset', draft personalized replies based on our help docs, and mark them as pending"
Team Performance — "List all conversations closed last week, group by assigned agent, calculate average response times, and identify top performers"
Knowledge Mining — "Find the 20 most common questions from the 'Technical Support' mailbox this month and suggest new help articles to write"

🔗 The Real Power: Combining Tools

AI can chain multiple Help Scout operations together:

Search conversations → Identify patterns → Create canned replies
List customers → Pull conversation history → Generate satisfaction scores
Monitor mailboxes → Detect SLA breaches → Notify team leads
Analyze tags → Identify trending issues → Draft internal reports

📦 What's Inside

7 API tools covering Help Scout customer support operations:

list_conversations — Browse tickets with filtering by status, mailbox, tags, and assignment
get_conversation — Full conversation thread with customer details and message history
create_conversation — Create new tickets programmatically (for automation)
reply_conversation — Reply to customers or add internal notes
list_customers — Search and browse customer records
list_mailboxes — Get all mailboxes and their settings
search — Advanced search with Help Scout query syntax

All with proper error handling, OAuth authentication, and TypeScript types.

🚀 Quick Start

Option 1: Claude Desktop (Local)

Clone and build:

git clone https://github.com/BusyBee3333/Help-Scout-MCP-2026-Complete.git
cd help-scout-mcp-2026-complete
npm install
npm run build

Get your Help Scout API credentials:
- Log into Help Scout → Your Profile → My Apps
- Create OAuth application or generate API key
- Copy your OAuth access token or API key

Configure Claude Desktop:

On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

On Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "helpscout": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/help-scout-mcp-2026-complete/dist/index.js"],
      "env": {
        "HELPSCOUT_ACCESS_TOKEN": "your-access-token-here"
      }
    }
  }
}

Restart Claude Desktop

Option 2: Deploy to Railway

Click the button above
Set HELPSCOUT_ACCESS_TOKEN in Railway dashboard
Use the Railway URL as your MCP server endpoint

Option 3: Docker

docker build -t helpscout-mcp .
docker run -p 3000:3000 \
  -e HELPSCOUT_ACCESS_TOKEN=your-token \
  helpscout-mcp

🔐 Authentication

Help Scout uses OAuth 2.0 or API Key authentication.

Get your API credentials:

Help Scout → Your Profile → My Apps
Create OAuth 2.0 application (recommended) or generate API key
For OAuth: complete authorization flow to get access token
For API Key: use directly as Bearer token

API Documentation: https://developer.helpscout.com/mailbox-api/

The MCP server handles OAuth token refresh automatically.

🎯 Example Prompts

Once connected to Claude, you can use natural language. Support-specific examples:

"Show me all open conversations in the 'General Support' mailbox"
"Get conversation #12345 with full thread history"
"Search for conversations about 'refund' from last week"
"List all customers who contacted us more than 5 times this month"
"Find pending conversations tagged 'bug' and assigned to Sarah"
"Create a new conversation from customer john@example.com about account access"
"Reply to conversation #67890 with: 'Thanks for reaching out...'"
"List all mailboxes and their unread counts"

🛠️ Development

Prerequisites

Node.js 18+
npm or yarn
Help Scout account with API access

Setup

git clone https://github.com/BusyBee3333/Help-Scout-MCP-2026-Complete.git
cd help-scout-mcp-2026-complete
npm install
cp .env.example .env
# Edit .env with your Help Scout credentials
npm run build
npm start

Testing

npm test                  # Run all tests
npm run test:watch        # Watch mode
npm run test:coverage     # Coverage report

🐛 Troubleshooting

"Authentication failed"

Verify your access token is correct
For OAuth: ensure your token hasn't expired (refresh it)
For API keys: check that it hasn't been revoked

"Tools not appearing in Claude"

Restart Claude Desktop after updating config
Check that the path in claude_desktop_config.json is absolute
Verify the build completed successfully (dist/index.js exists)

"Insufficient permissions"

Ensure your OAuth app has required scopes
Check that your Help Scout user role has API access enabled

📖 Resources

🤝 Contributing

Contributions are welcome! Please:

Fork the repo
Create a feature branch (git checkout -b feature/amazing-tool)
Commit your changes (git commit -m 'Add amazing tool')
Push to the branch (git push origin feature/amazing-tool)
Open a Pull Request

📄 License

MIT License - see LICENSE for details

🙏 Credits

Built by MCPEngage — AI infrastructure for business software.

Want more MCP servers? Check out our full catalog covering 30+ business platforms.

Questions? Open an issue or join our Discord community.

6.7 KiB Raw Permalink Blame History