Help Scout Mcp Server

by drewburchfield

467 downloads

Not rated

GitHub

About

An MCP server that enables AI assistants to interact with Help Scout data, such as customers and conversations.

Details

Author: drewburchfield
Downloads: 467
Categories: Communication, Other

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name Help Scout Mcp Server

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "help scout mcp server": {
            "helpscout": {
                "command": "npx",
                "args": [
                    "help-scout-mcp-server"
                ],
                "env": {
                    "HELPSCOUT_API_KEY": "Bearer your-personal-access-token-here",
                    "HELPSCOUT_BASE_URL": "https://api.helpscout.net/v2/",
                    "ALLOW_PII": "false",
                    "CACHE_TTL_SECONDS": "300",
                    "LOG_LEVEL": "info"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "help scout mcp server": {
            "helpscout": {
                "command": "npx",
                "args": [
                    "help-scout-mcp-server"
                ],
                "env": {
                    "HELPSCOUT_API_KEY": "Bearer your-personal-access-token-here",
                    "HELPSCOUT_BASE_URL": "https://api.helpscout.net/v2/",
                    "ALLOW_PII": "false",
                    "CACHE_TTL_SECONDS": "300",
                    "LOG_LEVEL": "info"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "help scout mcp server": {
            "helpscout": {
                "command": "npx",
                "args": [
                    "help-scout-mcp-server"
                ],
                "env": {
                    "HELPSCOUT_API_KEY": "Bearer your-personal-access-token-here",
                    "HELPSCOUT_BASE_URL": "https://api.helpscout.net/v2/",
                    "ALLOW_PII": "false",
                    "CACHE_TTL_SECONDS": "300",
                    "LOG_LEVEL": "info"
                }
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "help scout mcp server": {
            "helpscout": {
                "command": "npx",
                "args": [
                    "help-scout-mcp-server"
                ],
                "env": {
                    "HELPSCOUT_API_KEY": "Bearer your-personal-access-token-here",
                    "HELPSCOUT_BASE_URL": "https://api.helpscout.net/v2/",
                    "ALLOW_PII": "false",
                    "CACHE_TTL_SECONDS": "300",
                    "LOG_LEVEL": "info"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "help scout mcp server": {
            "helpscout": {
                "command": "npx",
                "args": [
                    "help-scout-mcp-server"
                ],
                "env": {
                    "HELPSCOUT_API_KEY": "Bearer your-personal-access-token-here",
                    "HELPSCOUT_BASE_URL": "https://api.helpscout.net/v2/",
                    "ALLOW_PII": "false",
                    "CACHE_TTL_SECONDS": "300",
                    "LOG_LEVEL": "info"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "help scout mcp server": {
            "helpscout": {
                "command": "npx",
                "args": [
                    "help-scout-mcp-server"
                ],
                "env": {
                    "HELPSCOUT_API_KEY": "Bearer your-personal-access-token-here",
                    "HELPSCOUT_BASE_URL": "https://api.helpscout.net/v2/",
                    "ALLOW_PII": "false",
                    "CACHE_TTL_SECONDS": "300",
                    "LOG_LEVEL": "info"
                }
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "help scout mcp server": {
            "helpscout": {
                "command": "npx",
                "args": [
                    "help-scout-mcp-server"
                ],
                "env": {
                    "HELPSCOUT_API_KEY": "Bearer your-personal-access-token-here",
                    "HELPSCOUT_BASE_URL": "https://api.helpscout.net/v2/",
                    "ALLOW_PII": "false",
                    "CACHE_TTL_SECONDS": "300",
                    "LOG_LEVEL": "info"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "help scout mcp server": {
            "helpscout": {
                "command": "npx",
                "args": [
                    "help-scout-mcp-server"
                ],
                "env": {
                    "HELPSCOUT_API_KEY": "Bearer your-personal-access-token-here",
                    "HELPSCOUT_BASE_URL": "https://api.helpscout.net/v2/",
                    "ALLOW_PII": "false",
                    "CACHE_TTL_SECONDS": "300",
                    "LOG_LEVEL": "info"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "help scout mcp server": {
            "helpscout": {
                "command": "npx",
                "args": [
                    "help-scout-mcp-server"
                ],
                "env": {
                    "HELPSCOUT_API_KEY": "Bearer your-personal-access-token-here",
                    "HELPSCOUT_BASE_URL": "https://api.helpscout.net/v2/",
                    "ALLOW_PII": "false",
                    "CACHE_TTL_SECONDS": "300",
                    "LOG_LEVEL": "info"
                }
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "help scout mcp server": {
            "helpscout": {
                "command": "npx",
                "args": [
                    "help-scout-mcp-server"
                ],
                "env": {
                    "HELPSCOUT_API_KEY": "Bearer your-personal-access-token-here",
                    "HELPSCOUT_BASE_URL": "https://api.helpscout.net/v2/",
                    "ALLOW_PII": "false",
                    "CACHE_TTL_SECONDS": "300",
                    "LOG_LEVEL": "info"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "help scout mcp server": {
            "helpscout": {
                "command": "npx",
                "args": [
                    "help-scout-mcp-server"
                ],
                "env": {
                    "HELPSCOUT_API_KEY": "Bearer your-personal-access-token-here",
                    "HELPSCOUT_BASE_URL": "https://api.helpscout.net/v2/",
                    "ALLOW_PII": "false",
                    "CACHE_TTL_SECONDS": "300",
                    "LOG_LEVEL": "info"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "help scout mcp server": {
            "helpscout": {
                "command": "npx",
                "args": [
                    "help-scout-mcp-server"
                ],
                "env": {
                    "HELPSCOUT_API_KEY": "Bearer your-personal-access-token-here",
                    "HELPSCOUT_BASE_URL": "https://api.helpscout.net/v2/",
                    "ALLOW_PII": "false",
                    "CACHE_TTL_SECONDS": "300",
                    "LOG_LEVEL": "info"
                }
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "help scout mcp server": {
            "helpscout": {
                "command": "npx",
                "args": [
                    "help-scout-mcp-server"
                ],
                "env": {
                    "HELPSCOUT_API_KEY": "Bearer your-personal-access-token-here",
                    "HELPSCOUT_BASE_URL": "https://api.helpscout.net/v2/",
                    "ALLOW_PII": "false",
                    "CACHE_TTL_SECONDS": "300",
                    "LOG_LEVEL": "info"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "help scout mcp server": {
            "helpscout": {
                "command": "npx",
                "args": [
                    "help-scout-mcp-server"
                ],
                "env": {
                    "HELPSCOUT_API_KEY": "Bearer your-personal-access-token-here",
                    "HELPSCOUT_BASE_URL": "https://api.helpscout.net/v2/",
                    "ALLOW_PII": "false",
                    "CACHE_TTL_SECONDS": "300",
                    "LOG_LEVEL": "info"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "help scout mcp server": {
            "helpscout": {
                "command": "npx",
                "args": [
                    "help-scout-mcp-server"
                ],
                "env": {
                    "HELPSCOUT_API_KEY": "Bearer your-personal-access-token-here",
                    "HELPSCOUT_BASE_URL": "https://api.helpscout.net/v2/",
                    "ALLOW_PII": "false",
                    "CACHE_TTL_SECONDS": "300",
                    "LOG_LEVEL": "info"
                }
            }
        }
    }
}

From the repository

Install via NPM, Docker, or direct installation. Configure with your Help Scout API credentials and choose between Personal Access Token or OAuth2 authentication. Full TypeScript support is included.

`searchInboxes`

STEP 1: Always use this FIRST when searching conversations. Lists all available inboxes or filters by name. CRITICAL: When a user mentions an inbox by name (e.g., "support inbox", "sales mailbox"), you MUST call this tool first to get the inbox ID before searching conversations.

`searchConversations`

STEP 2: Search conversations after obtaining inbox ID. WARNING: Always get inboxId from searchInboxes first if user mentions an inbox name. IMPORTANT: Specify status (active/pending/closed/spam) for better results, or use comprehensiveConversationSearch for multi-status searching.

`getConversationSummary`

Get conversation summary with first customer message and latest staff reply

`getThreads`

Get all thread messages for a conversation

`getServerTime`

Get current server time for time-relative searches

`listAllInboxes`

QUICK HELPER: Lists ALL available inboxes with their IDs. This is equivalent to searchInboxes with empty query but more explicit. Use this when you need to see all inboxes or when starting any inbox-specific search.

`advancedConversationSearch`

Advanced conversation search with complex boolean queries and customer organization support

`comprehensiveConversationSearch`

RECOMMENDED FOR GENERAL SEARCHES: Searches across multiple statuses simultaneously, solving the common issue where searches return no results. WORKFLOW: 1) If user mentions an inbox name, call searchInboxes FIRST to get the ID. 2) Then use this tool with the inbox ID. This tool automatically searches active, pending, and closed conversations.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "help scout mcp server": {
            "helpscout": {
                "command": "npx",
                "args": [
                    "help-scout-mcp-server"
                ],
                "env": {
                    "HELPSCOUT_API_KEY": "Bearer your-personal-access-token-here",
                    "HELPSCOUT_BASE_URL": "https://api.helpscout.net/v2/",
                    "ALLOW_PII": "false",
                    "CACHE_TTL_SECONDS": "300",
                    "LOG_LEVEL": "info"
                }
            }
        }
    }
}

McpServers

{
    "helpscout": {
        "command": "npx",
        "args": [
            "help-scout-mcp-server"
        ],
        "env": {
            "HELPSCOUT_API_KEY": "Bearer your-personal-access-token-here",
            "HELPSCOUT_BASE_URL": "https://api.helpscout.net/v2/",
            "ALLOW_PII": "false",
            "CACHE_TTL_SECONDS": "300",
            "LOG_LEVEL": "info"
        }
    }
}

AnMCP serverthat gives AI assistants direct access to your Help Scout inboxes, conversations, customers, organizations, threads, and Docs knowledge base. Search tickets, pull customer and account context, inspect articles, spot patterns, and get answers without leaving your editor or chat window.

Built by a Help Scout customer who wanted to give his support team superpowers. If you handle customer conversations in Help Scout and want AI to help you work faster, this is for you.

- Search conversationsby keyword, date range, status, tag, email domain, or ticket number
- Look up customersby name, advanced query syntax, or exact email address
- Explore organizationswith direct customer and conversation traversal
- Inspect conversation detailwith raw ticket metadata, summaries, full threads, attachments, and original source
- Pull full thread historyinto context before drafting a reply
- Get conversation summarieswith the original customer message and latest staff response
- Search and retrieve Docs articlesfrom the separate Help Scout Docs API
- Pull Help Scout reports and metadatafor company, conversations, Docs, channels, productivity, happiness, users, teams, system users, statuses, routing, and webhooks
- Monitor inbox activityacross multiple inboxes with a single query
- Take action with opt-in writes: draft replies, internal notes, tags, status, assignment, snooze, and more, all off by default
- Reduce message payloadswith optional message content redaction and scoped inbox access

Claude Desktop & Claude Cowork (Recommended)

One-click installusing Desktop Extensions. One install covers both Chat and Cowork sessions in the Claude desktop app.
- Download the latest .mcpbfile from releases
- Double-click to install (or drag into Claude Desktop)
- Enter your Help Scout App ID and App Secret in the extension settings; the settings also carry toggles for message redaction and the opt-in write surface
- Restart Claude Desktop

If the tools don't show up in a Cowork session, update the desktop app to the latest version and start a fresh session. (Cowork walkthrough)

Optional: add thehelpscout-navigatorskill so Claude picks the right operation faster. Go toCustomize, click+>Add marketplace from GitHub, enterdrewburchfield/help-scout-mcp-server, and installhelpscout-navigator.

Register the server, then optionally add thehelpscout-navigatorskill, which teaches Claude to pick the right operation for each query.

claude mcp add helpscout \ --env HELPSCOUT_APP_ID=your-app-id \ --env HELPSCOUT_APP_SECRET=your-app-secret \ -- npx -y help-scout-mcp-server

- Run/plugin marketplace add drewburchfield/help-scout-mcp-server
- Run/plugin install helpscout-navigator

The server alone gives you the tools; the skill also teaches the AI how to use them well.

For Cursor, VS Code, and Other MCP Clients

Add to your MCP client's config file (e.g.,claude_desktop_config.json,.cursor/mcp.json):

{ "mcpServers": { "helpscout": { "command": "npx", "args": ["help-scout-mcp-server@2.1.0"], "env": { "HELPSCOUT_APP_ID": "your-app-id", "HELPSCOUT_APP_SECRET": "your-app-secret", "HELPSCOUT_DOCS_API_KEY": "optional-docs-api-key" } } } }

docker run -e HELPSCOUT_APP_ID="your-app-id" \ -e HELPSCOUT_APP_SECRET="your-app-secret" \ -e HELPSCOUT_DOCS_API_KEY="optional-docs-api-key" \ drewburchfield/help-scout-mcp-server:2.1.0

- Go toHelp Scout>My Apps>Create Private App
- Copy yourApp IDandApp Secret

Help Scout uses OAuth2 Client Credentials flow exclusively. Personal Access Tokens are not supported. The app authenticates as the user who created it, with that user's permissions; there is no separate scope selection, which is why the server's own write gating defaults to off.

Alternative namesHELPSCOUT_CLIENT_ID/HELPSCOUT_CLIENT_SECRETare also supported.

Docs knowledge base tools use Help Scout Docs API v1, which is separate from the Mailbox API. SetHELPSCOUT_DOCS_API_KEYonly if you want to uselistDocs*,searchDocsArticles,getDocsArticle, or redirect tools.

The server advertises three tools that together reach every supported read operation (55 across the Mailbox and Docs APIs):

This keeps the advertised surface small enough that AI clients don't drown in schemas, while every read capability stays one search away. Operations in the current registry also remain callable by name directly. Tool names removed in the v2.0.0 consolidation (for examplecomprehensiveConversationSearch,structuredConversationFilter, andsearchInboxes) are not; their capabilities live insearchConversationsandlistAllInboxes.

An optional fourth tool,write_help_scout, appears only when an operator turns writes on. SeeWrite operations (opt-in).

For the MCP compatibility contract and roadmap, see:

- MCP tool contract
- MCP vs CLI boundary
- MCP tool surface roadmap

Inboxes are auto-discovered when the server connects. AI agents get inbox IDs in their instructions automatically, so no lookup step is needed.

A default install is read-only. It advertises the three tools above and nothing else, unchanged from 2.0. Writes exist only after an operator sets a flag.

Tier 1 covers draft replies, internal notes, status changes, assign and unassign, adding and removing tags, custom field values, snooze and unsnooze, and moving a conversation to another inbox. None of it emails anyone: a draft is saved unsent, and a note is visible to teammates only.

Tier 2 is the only path that reaches a customer, and it needs both flags. Every call tosendReplyorpublishDraftmust also carry confirmation naming the operation and the target:

{ "name": "sendReply", "arguments": { "conversationId": "12345", "text": "..." }, "confirm": true, "confirmOperation": "sendReply", "targetId": "12345" }

Missing, false, or mismatched confirmation is refused before anything reaches Help Scout. Deletes and admin configuration writes are deliberately not exposed, under any flag.

Set"dryRun": trueon any write to validate the arguments and see the exact request that would be sent, without contacting Help Scout.

Built with security-minded teams in mind:

- Optional message content redaction.Message bodies are included by default. SetREDACT_MESSAGE_CONTENT=trueto replace conversation and thread bodies with placeholders for lower-context analysis. This is not a compliance boundary and does not remove all customer identifiers.
- Secure authentication.OAuth2 Client Credentials with automatic token refresh.
- Rate limit handling.Automatic retry with exponential backoff on 429 responses.
- Scoped access.Optional default inbox configuration limits what the AI can search.

Authentication failed?Verify your credentials work with Help Scout directly:

curl -X POST https://api.helpscout.net/v2/oauth2/token \ -d "grant_type=client_credentials&client_id=$HELPSCOUT_APP_ID&client_secret=$HELPSCOUT_APP_SECRET"

- Forgetting thatsearchConversationsis the single search tool: usecontentTerms/subjectTermsfor keyword search, plain filters for listing
- Inbox ID mismatch. Check the IDs from server instructions, not guessed values.
- Search terms too narrow. Try broader terms or a longer time range.

LOG_LEVEL=debug npx help-scout-mcp-server@2.1.0

git clone https://github.com/drewburchfield/help-scout-mcp-server.git cd help-scout-mcp-server npm install && npm run build npm start

npm test # Run tests npm run type-check # TypeScript validation npm run lint # Linting npm run dev # Development server with auto-reload

Contributions welcome. Please ensure tests, type checking, and linting pass before submitting a PR.

- GitHub Issues
- GitHub Discussions
- NPM Package
- Changelog

Search and read support tickets from Jitbit Helpdesk via AI assistants. Works with SaaS and on-premise installations.

Connect Tidio with your website via MCP. Embed the widget without exiting your programming environment.

A high-performance MCP server for analyzing Intercom conversations with fast, local access via caching and background sync.

AI phone secretary for businesses: place outbound calls and read transcripts, leads, voicemails, SMS, and analytics from your business line.

Provides access to Intercom conversations and chats. Requires an Intercom API key.

Access and analyze customer support data from Intercom.

Salesforce MCP Server - Enhanced Edition

A Salesforce MCP server with automatic integrations for services such as WhatsApp, Slack, email, and custom webhooks.

Hosted, Stateless & Multitenant Google Business Profile MCP server enables AI assistants to manage business listings, reviews, locations, and customer interactions through Google Business Profile.

A powerful, production-ready Model Context Protocol (MCP) server for Zammad - the open-source helpdesk and ticket system.

Build with the Kudosity API to send SMS and MMS. Access developer docs, API references and live testing tools to send messages, manage contact lists, configure webhooks and more.

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

searchInboxes

searchConversations

getConversationSummary

getThreads

getServerTime

listAllInboxes

advancedConversationSearch

comprehensiveConversationSearch

Claude Desktop / Cursor

McpServers

Claude Desktop & Claude Cowork (Recommended)

For Cursor, VS Code, and Other MCP Clients

Salesforce MCP Server - Enhanced Edition

Install

More like this

Sequential Thinking

Slack

Filesystem

EverArt

Google Drive

Reactive Resume

`searchInboxes`

`searchConversations`

`getConversationSummary`

`getThreads`

`getServerTime`

`listAllInboxes`

`advancedConversationSearch`

`comprehensiveConversationSearch`