> **🚀 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

[![Deploy on Railway](https://railway.app/button.svg)](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).