MCP Help Scout
A comprehensive Model Context Protocol (MCP) server for the full Help Scout API — covering both the Docs API and the Inbox API.
Most existing Help Scout MCPs only cover conversations/messages. This one provides complete coverage of Help Scout's knowledge base (Docs) in addition to inbox functionality.
Features
Docs API (v1)
Full CRUD operations for Help Scout's knowledge base:
- Sites — List, get, create, update, delete
- Collections — List, get, create, update, delete
- Categories — List, get, create, update, reorder, delete
- Articles — List, search, get, create, update, delete, drafts, revisions
- Redirects — List, get, create, update, delete
Inbox API (v2)
Core inbox operations:
- Conversations — List, get, create, delete
- Threads — List, reply, add notes
- Customers — List, get, create
- Mailboxes — List, get
- Users — List, get, get current user
- Tags — List
Setup
Prerequisites
- Node.js 18+
- Help Scout API credentials (see below)
Installation
npm install -g @solveitsimply/mcp-helpscout
Or clone and build locally:
git clone https://github.com/solveitsimply/mcp-helpscout.git
cd mcp-helpscout
npm install
npm run build
Environment Variables
| Variable | Required For | Description |
|---|---|---|
HELPSCOUT_API_KEY | Docs API | API key from Help Scout → Profile → Authentication → API Keys |
HELPSCOUT_APP_ID | Inbox API | OAuth app ID from Help Scout → Manage → Apps → My Apps |
HELPSCOUT_APP_SECRET | Inbox API | OAuth app secret |
You can use just the Docs API key, just the Inbox OAuth credentials, or both.
VS Code MCP Configuration
Add to .vscode/mcp.json:
{
"servers": {
"mcp-helpscout": {
"type": "stdio",
"command": "node",
"args": ["/path/to/mcp-helpscout/dist/index.js"],
"env": {
"HELPSCOUT_API_KEY": "your-docs-api-key",
"HELPSCOUT_APP_ID": "your-app-id",
"HELPSCOUT_APP_SECRET": "your-app-secret"
}
}
}
}
Or using shell to read from .env.local:
{
"servers": {
"mcp-helpscout": {
"type": "stdio",
"command": "sh",
"args": [
"-c",
"export $(grep -E '^HELPSCOUT_' /path/to/.env.local | xargs) && exec node /path/to/mcp-helpscout/dist/index.js"
]
}
}
}
Available Tools
Docs API Tools
| Tool | Description |
|---|---|
docs_list_sites | List all Docs sites |
docs_get_site | Get a site by ID |
docs_create_site | Create a new site |
docs_update_site | Update a site |
docs_delete_site | Delete a site |
docs_list_collections | List collections (filter by site, visibility) |
docs_get_collection | Get a collection by ID |
docs_create_collection | Create a collection |
docs_update_collection | Update a collection |
docs_delete_collection | Delete a collection |
docs_list_categories | List categories in a collection |
docs_get_category | Get a category by ID |
docs_create_category | Create a category |
docs_update_category | Update a category |
docs_update_category_order | Reorder categories |
docs_delete_category | Delete a category |
docs_list_articles | List articles in a collection or category |
docs_search_articles | Search articles by query |
docs_get_article | Get full article with content |
docs_create_article | Create an article |
docs_update_article | Update an article |
docs_delete_article | Delete an article |
docs_list_related_articles | List related articles |
docs_list_revisions | List article revisions |
docs_get_revision | Get a specific revision |
docs_save_draft | Save an article draft |
docs_delete_draft | Delete an article draft |
docs_list_redirects | List URL redirects for a site |
docs_get_redirect | Get a redirect by ID |
docs_create_redirect | Create a redirect |
docs_update_redirect | Update a redirect |
docs_delete_redirect | Delete a redirect |
Inbox API Tools
| Tool | Description |
|---|---|
inbox_list_conversations | List conversations (filter by mailbox, status, tag) |
inbox_get_conversation | Get conversation details |
inbox_create_conversation | Create a new conversation |
inbox_delete_conversation | Delete a conversation |
inbox_list_threads | List threads in a conversation |
inbox_create_reply | Send a reply in a conversation |
inbox_create_note | Add an internal note |
inbox_list_customers | List/search customers |
inbox_get_customer | Get customer details |
inbox_create_customer | Create a customer |
inbox_list_mailboxes | List mailboxes |
inbox_get_mailbox | Get mailbox details |
inbox_list_users | List team members |
inbox_get_user | Get user details |
inbox_get_me | Get authenticated user |
inbox_list_tags | List all tags |
Authentication Details
Docs API
Uses HTTP Basic Authentication with the API key as the username and X as the password. The API key is associated with a Help Scout user account.
Base URL: https://docsapi.helpscout.net/v1
Inbox API
Uses OAuth 2.0 client credentials flow. The server automatically handles token acquisition and renewal.
Base URL: https://api.helpscout.net/v2
License
MIT