205 lines
6.7 KiB
Markdown
205 lines
6.7 KiB
Markdown
> **🚀 Don't want to self-host?** [Join the waitlist for our fully managed solution →](https://mcpengage.com/helpscout)
|
|
>
|
|
> 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:
|
|
|
|
1. **Smart Triage** — "Find all open conversations tagged 'urgent' or 'billing' from the last 24 hours, summarize each issue, and suggest priority order"
|
|
|
|
2. **Customer Intelligence** — "Pull Sarah Johnson's conversation history, identify recurring issues, check response times, and generate a support quality report"
|
|
|
|
3. **Automated Responses** — "Search for conversations about 'password reset', draft personalized replies based on our help docs, and mark them as pending"
|
|
|
|
4. **Team Performance** — "List all conversations closed last week, group by assigned agent, calculate average response times, and identify top performers"
|
|
|
|
5. **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)
|
|
|
|
1. **Clone and build:**
|
|
```bash
|
|
git clone https://github.com/BusyBee3333/Help-Scout-MCP-2026-Complete.git
|
|
cd help-scout-mcp-2026-complete
|
|
npm install
|
|
npm run build
|
|
```
|
|
|
|
2. **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
|
|
|
|
3. **Configure Claude Desktop:**
|
|
|
|
On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
|
|
On Windows: `%APPDATA%\Claude\claude_desktop_config.json`
|
|
|
|
```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"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
4. **Restart Claude Desktop**
|
|
|
|
### Option 2: Deploy to Railway
|
|
|
|
[](https://railway.app/template/helpscout-mcp)
|
|
|
|
1. Click the button above
|
|
2. Set `HELPSCOUT_ACCESS_TOKEN` in Railway dashboard
|
|
3. Use the Railway URL as your MCP server endpoint
|
|
|
|
### Option 3: Docker
|
|
|
|
```bash
|
|
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:**
|
|
1. Help Scout → Your Profile → My Apps
|
|
2. Create OAuth 2.0 application (recommended) or generate API key
|
|
3. For OAuth: complete authorization flow to get access token
|
|
4. 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
- [Help Scout Mailbox API Documentation](https://developer.helpscout.com/mailbox-api/)
|
|
- [MCP Protocol Specification](https://modelcontextprotocol.io/)
|
|
- [Claude Desktop Documentation](https://claude.ai/desktop)
|
|
|
|
## 🤝 Contributing
|
|
|
|
Contributions are welcome! Please:
|
|
|
|
1. Fork the repo
|
|
2. Create a feature branch (`git checkout -b feature/amazing-tool`)
|
|
3. Commit your changes (`git commit -m 'Add amazing tool'`)
|
|
4. Push to the branch (`git push origin feature/amazing-tool`)
|
|
5. Open a Pull Request
|
|
|
|
## 📄 License
|
|
|
|
MIT License - see [LICENSE](LICENSE) for details
|
|
|
|
## 🙏 Credits
|
|
|
|
Built by [MCPEngage](https://mcpengage.com) — AI infrastructure for business software.
|
|
|
|
Want more MCP servers? Check out our [full catalog](https://mcpengage.com) covering 30+ business platforms.
|
|
|
|
---
|
|
|
|
**Questions?** Open an issue or join our [Discord community](https://discord.gg/mcpengage).
|