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