Help ScoutBLOCK
mcp/drewburchfield/help-scout
MCP server for Help Scout - search conversations, customers, organizations, reports, and Docs with AI agents, plus opt-in writes for drafting replies and triage
Verdict
BLOCK
Grade
D
Trust score
68 /100
Exposed tools
81 68r · 10w · 3d
Transport
stdio
License
MIT
Stars
47
01
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
[](https://github.com/drewburchfield/help-scout-mcp-server)
[](https://badge.fury.io/js/help-scout-mcp-server) [](https://hub.docker.com/r/drewburchfield/help-scout-mcp-server) [](https://deepwiki.com/drewburchfield/help-scout-mcp-server) [](https://opensource.org/licenses/MIT)
An MCP server that 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.
What You Can Do
- Search conversations by keyword, date range, status, tag, email domain, or ticket number
- Look up customers by name, advanced query syntax, or exact email address
- Explore organizations with direct customer and conversation traversal
- Inspect conversation detail with raw ticket metadata, summaries, full threads, attachments, and original source
- Pull full thread history into context before drafting a reply
- Get conversation summaries with the original customer message and latest staff response
- Search and retrieve Docs articles from the separate Help Scout Docs API
- Pull Help Scout reports and metadata
Read from source at commit
683538564abaOBSERVED · 2026-10-0802
Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control. Replace the environment placeholders with a token scoped to the least it needs.
claude-code (npm)
claude mcp add help-scout-mcp-server --env HELPSCOUT_APP_ID=${HELPSCOUT_APP_ID} --env HELPSCOUT_APP_SECRET=${HELPSCOUT_APP_SECRET} --env HELPSCOUT_DOCS_API_KEY=${HELPSCOUT_DOCS_API_KEY} --env HELPSCOUT_APP_ID=${HELPSCOUT_APP_ID} -- npx -y [email protected]claude-code (oci)
claude mcp add help-scout-mcp-server:2.1.0 --env HELPSCOUT_APP_ID=${HELPSCOUT_APP_ID} --env HELPSCOUT_APP_SECRET=${HELPSCOUT_APP_SECRET} --env HELPSCOUT_DOCS_API_KEY=${HELPSCOUT_DOCS_API_KEY} --env HELPSCOUT_APP_ID=${HELPSCOUT_APP_ID} -- docker run -i --rm docker.io/drewburchfield/help-scout-mcp-server:2.1.0:None03
Exposed tools (81)
68 read · 10 write · 3 destructive. Blast radius: 3 tools can delete or overwrite — an agent that can be talked into calling a tool can be talked into calling this one.
| Tool | Risk | Description |
|---|---|---|
assignConversation | read | Assign a Help Scout conversation to a user. Reversible with assignConversation or unassignConversation. |
call_tool | write | Execute one selected Help Scout read operation using arguments that match its loaded schema. |
createDraftReply | write | Compose a customer reply and save it as an unsent draft on a Help Scout conversation. The draft flag is pinned on: this operation cannot send. Use sendReply or publishDraft, both of which require the customer-visible write flag and per-call confirmation, to actually email the customer. |
createNote | write | Add an internal note to a Help Scout conversation. Notes are visible to teammates only and never notify the customer. The Mailbox API has no endpoint to delete a note. |
downloadAttachmentFile | read | Download a Help Scout attachment file as base64 with response metadata. |
find-urgent-tags | read | Find conversations with urgent or priority tags |
findDocsRedirect | read | Resolve a Help Scout Docs redirect target from a site ID and URL path. |
getAttachment | read | Get base64-encoded Help Scout attachment data by conversation and attachment ID. |
getChannelReport | read | Get a Help Scout channel report for a bounded time range. channel selects /reports/chat, /reports/email, or /reports/phone. |
getCompanyReport | read | Get a Help Scout company report for a bounded time range. report=overall (/reports/company), customers-helped (/reports/company/customers-helped), or drilldown (/reports/company/drilldown). |
getConversation | read | Get the raw Help Scout conversation object by ID. Optionally embeds threads for direct API parity; use getThreads when full thread pagination is needed. Set includeSystemActors to distinguish user, team, and system_user person types. |
getConversationSummary | read | Get conversation summary with first customer message and latest staff reply |
getConversationsReport | read | Get a Help Scout conversations report for a bounded time range. report selects /reports/conversations[/<report>]: overall, volume-by-channel, busy-times, drilldown, fields-drilldown, new, new-drilldown, received-messages. |
getCustomer | read | Get a customer profile by ID. Returns profile with contact details (emails, phones, chat handles, social profiles, websites) plus address from a separate lookup. |
getCustomerContacts | read | Get all contact details for a customer: emails, phones, chat handles, social profiles, websites, and address. Calls dedicated sub-resource endpoints for complete data. Use after getCustomer or listCustomers. |
getDocsArticle | read | Get one Help Scout Docs article by ID or number. |
getDocsArticleRevision | read | Get one Help Scout Docs article revision by ID. |
getDocsCategory | read | Get one Help Scout Docs category by ID or number. |
getDocsCollection | read | Get one Help Scout Docs collection by ID or number. |
getDocsRedirect | read | Get one Help Scout Docs redirect by ID. |
getDocsReport | read | Get the Help Scout Docs overall report for a bounded time range. |
getDocsSite | write | Get one Help Scout Docs site by ID. Set includeRestrictions to also attach the restricted-site settings (secrets redacted). |
getHappinessReport | read | Get a Help Scout happiness report for a bounded time range. report=overall (/reports/happiness) or ratings (/reports/happiness/ratings). |
getInbox | read | Get one Help Scout inbox by ID, including inbox email and resource links. Pass include to fan out and attach sub-resources in one call: |
getOrganization | read | Get an organization by ID with optional customer/conversation counts. |
getOrganizationConversations | read | Get all conversations associated with an organization. Traverses org-to-conversations without needing individual customer lookups. Returns 50 per page. |
getOrganizationMembers | read | Get all customers belonging to an organization. Use after getOrganization to see who is in the org. Returns 50 per page. |
getOrganizationProperty | read | Get one organization property definition by slug. Use after listOrganizationProperties when exact option labels are needed. |
getOriginalSource | write | Get the original source for a Help Scout conversation thread. Set format to |
getProductivityReport | read | Get a Help Scout productivity report for a bounded time range. report selects /reports/productivity[/<report>]: overall, first-response-time, replies-sent, resolved, response-time, resolution-time. |
getSatisfactionRating | read | Get a Help Scout satisfaction rating by ID. |
getSavedReply | read | Get one saved reply from a Help Scout inbox by ID. |
getServerTime | read | Get the current MCP host timestamp. Use before date-relative searches to calculate time ranges. |
getTag | read | Get a Help Scout tag by ID. Use after listTags when an exact tag record is needed. |
getTeamMembers | read | List members of a Help Scout team. Use after listTeams to discover user IDs in a team. |
getThing | read | a |
getThreads | read | Retrieve full message history for a conversation. Returns all thread messages. Set includeSystemActors to distinguish user, team, and system_user person types. |
getUser | read | Get a Help Scout user by ID, or pass |
getUserReport | read | Get a Help Scout user or team report for a bounded time range. report selects /reports/user[/<report>]: overall, conversation-history, customers-helped, drilldown, happiness, ratings, replies, resolutions, chat. |
getWebhook | read | Get a Help Scout webhook by ID. |
get_tool_schema | read | Return the full input schemas for selected Help Scout read operations. |
helpscout-best-practices | write | Essential workflow guide for using Help Scout MCP effectively - START HERE for correct search patterns |
hours | read | Required: Number of hours to look back |
inboxId | read | Optional: Specific inbox ID to search within |
includeThreads | read | Optional: Whether to include thread details (default: false) |
list-inbox-activity | read | Show activity in a given inbox over the last N hours |
listAllInboxes | read | List all inboxes with IDs. Pass nameContains to filter by a case-insensitive name substring. Deprecated: inbox IDs now in server instructions. Only needed mid-session. |
listCustomerProperties | read | List customer property definitions. Use to interpret custom property values embedded on customer records. |
listCustomers | read | List or search customers by name, query syntax, or dates. Defaults to v2 page-based pagination. Set useV3 (or pass a cursor) to use the v3 Customers API with cursor pagination, which also enables the email and createdSince filters. |
listDocsArticleRevisions | read | List Help Scout Docs article revisions. |
listDocsArticles | read | List Help Scout Docs articles for a collection or category. |
listDocsCategories | read | List Help Scout Docs categories for a collection. |
listDocsCollections | read | List Help Scout Docs collections, optionally scoped to a site. |
listDocsRedirects | read | List Help Scout Docs redirects for a site. |
listDocsRelatedArticles | read | List Help Scout Docs articles related to an article. |
listDocsSites | read | List Help Scout Docs sites using the Docs API v1. |
listOrganizationProperties | read | List organization property definitions. Use to interpret custom company property values embedded on organizations. |
listOrganizations | read | List all organizations with sorting options. Use for discovering organizations before drilling into members or conversations. Returns 50 per page. |
listSavedReplies | read | List saved replies for a Help Scout inbox. Use to discover saved reply IDs and inspect reusable response templates. |
listTags | read | List Help Scout tags used across inboxes. Use to discover tag IDs and exact names before filtering conversations or reports. |
listTeams | read | List Help Scout teams. Use to discover team IDs before team-member lookup or team-scoped reporting. |
listUsers | read | List Help Scout users with optional exact email or inbox filter. Use to discover assignee IDs, mentions, and roles. Set includeStatuses to attach all user availability statuses; set includeSystemActors to list v3 system users (AI agents, integrations) instead. |
listWebhooks | read | List Help Scout webhooks. Use to inspect webhook configuration and discover webhook IDs. |
listWorkflows | read | List Help Scout workflows. Use to inspect account workflow configuration and discover workflow IDs. |
moveConversation | write | Move a Help Scout conversation to a different inbox. Reversible by moving it back to the original inbox. |
publishDraft | write | Publish a Help Scout draft by clearing its draft flag, which sends the pending reply to the customer. This cannot be undone. Requires HELPSCOUT_ENABLE_CUSTOMER_VISIBLE_WRITES and per-call confirmation. |
removeConversationTags | destructive | Remove tags from a Help Scout conversation, keeping the rest. Help Scout replaces the whole tag list on every update, so this operation reads the current tags first and sends the remaining list; a tag added by someone else between that read and the write is lost. Reversible with addConversationTags. |
search-last-7-days | read | Search recent conversations across all inboxes from the last 7 days |
searchConversations | read | Search and list conversations. Filter by status, date range, inbox, or tags, and search content with contentTerms/subjectTerms, email/emailDomain, customerIds, assignedTo, folderId, or conversationNumber. Searches all statuses by default. |
searchCustomersByEmail | read | Search customers by email address using the v3 API. Provides email as a dedicated filter parameter (vs query syntax in v2) and cursor-based pagination. |
searchDocsArticles | read | Search Help Scout Docs articles by query, site, collection, status, or visibility. |
search_help_scout | read | colliding operation |
search_tools | read | Search ${operationCount} Help Scout read capabilities by user intent. Returns operation names and descriptions without loading every schema. |
sendReply | write | Send a reply to the customer on a Help Scout conversation. This emails the customer immediately and cannot be recalled. Requires HELPSCOUT_ENABLE_CUSTOMER_VISIBLE_WRITES and per-call confirmation. Use createDraftReply to compose without sending. |
snoozeConversation | read | Snooze a Help Scout conversation until a future time. Each call replaces any previous snooze. Reversible with unsnoozeConversation. |
status | read | Optional: Filter by conversation status (active, pending, closed, spam) |
tag | read | Optional: Filter by specific tag |
timeframe | read | Optional: Time period to search (e.g., |
unassignConversation | destructive | Clear the assignee on a Help Scout conversation, returning it to the unassigned queue. Reversible with assignConversation. |
unsnoozeConversation | destructive | Remove the snooze from a Help Scout conversation, returning it to its home folder and reactivating it if needed. Reversible with snoozeConversation. |
updateConversationStatus | write | Set a Help Scout conversation to active, closed, or pending. Reversible by setting the previous status again. |
04
Trust audit
BLOCKgrade D · trust 68/100 Do not install this without reading the findings. The audit found something that could harm you or your machine.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | PASS |
| L1 | Static analysis of the code | FAIL |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | WARN |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- declared (2 observation(s))
- Network
- declared (6 observation(s))
- Shell
- declared (8 observation(s))
- Dependencies
- not all pinned
- Secrets in source
- found
Findings (16)
HIGHCode injection · code.eval_exec · CWE-78, CWE-94, CWE-95
.semgrep.yml:120
- pattern: eval(...)
Why it matters. evaluates text as code
Fix. remove; use a parser or a dispatch table
HIGHCode injection · code.eval_exec · CWE-78, CWE-94, CWE-95
.semgrep.yml:130
exec($CMD)
Why it matters. evaluates text as code
Fix. remove; use a parser or a dispatch table
MEDIUMInformation disclosure · disclose.log_secret · CWE-209, CWE-532
scripts/verify-credentials.ts:82
console.log(`✅ Authentication successful! Token expires in ${response.data.expires_in} seconds`);MEDIUMNetwork egress · net.raw_ip · CWE-200, CWE-319
evals/run-tool-surface-discriminator.mjs:11
const ENDPOINT = 'http://127.0.0.1:8317/v1/chat/completions';
MEDIUMHard-coded secrets · secret.generic · CWE-798, CWE-321
tests/dogfood-fixtures.ts:50
secret: 'mcp-test-dogfood-secret',
MEDIUMFilesystem / path · mcp.destructive_tools · CWE-22, CWE-59
removeConversationTags, unassignConversation, unsnoozeConversation
Why it matters. 3 tool(s) can delete or overwrite
Fix. prefer a read-only mode or scoped tokens; the page states the blast radius
LOWInventory / provenance · inv.hidden_file · CWE-1104
.semgrep.yml
.semgrep.yml
Why it matters. hidden member outside the usual dotfiles
Fix. review its purpose
LOWInventory / provenance · inv.hidden_file · CWE-1104
.semgrepignore
.semgrepignore
Why it matters. hidden member outside the usual dotfiles
Fix. review its purpose
LOWInventory / provenance · inv.hidden_file · CWE-1104
helpscout-mcp-extension/.dxtignore
.dxtignore
Why it matters. hidden member outside the usual dotfiles
Fix. review its purpose
LOWFilesystem / path · fs.traversal · CWE-22, CWE-59
src/__tests__/dogfood-fixtures.test.ts:5
} from '../../tests/dogfood-fixtures.js';
LOWSupply chain · supply.unpinned · CWE-829, CWE-1357
package.json
axios, dotenv, lru-cache, zod, @types/jest, @types/nock, @types/node, @typescript-eslint/eslint-plugin
Why it matters. 16 dependency range(s) float
Fix. pin exact versions or ship a lockfile
LOWPrompt injection · prompt.transfer_instruction · CWE-94, CWE-1427
README.md:219
curl -X POST https://api.helpscout.net/v2/oauth2/token \
Why it matters. an instruction to move sensitive data to an outside destination
Fix. remove; a skill never needs the user's secrets off the machine
LOWPrompt injection · prompt.transfer_instruction · CWE-94, CWE-1427
guides/cowork-setup.md:47
There is a second, separate toggle, **Enable Customer-Visible Writes (Sends Email)**. Turning it on additionally allows `sendReply` and `publishDraft`, both of which email the customer immediately and
Why it matters. an instruction to move sensitive data to an outside destination
Fix. remove; a skill never needs the user's secrets off the machine
LOWPrompt injection · prompt.transfer_instruction · CWE-94, CWE-1427
guides/testing/dogfood-fixture-matrix.md:63
| Original email source | Real inbound email-source fixture in the test account. The API can create/import conversations and replies, but original source endpoints are read-only retrieval endpoints; A
Why it matters. an instruction to move sensitive data to an outside destination
Fix. remove; a skill never needs the user's secrets off the machine
INFOPrompt injection · prompt.credential_read · CWE-94, CWE-1427
guides/architecture/mcp-tool-contract.md:20
- Help Scout credentials are read from environment variables for stdio clients.
Why it matters. asks the agent to read credentials
INFOPrompt injection · prompt.credential_read · CWE-94, CWE-1427
guides/cowork-setup.md:49
Writes run with the same user permissions as reads; a credential whose user cannot write to a mailbox gets a structured permission error. Because the API offers no read-only credential tier, these tog
Why it matters. asks the agent to read credentials
Gates applied: no_behavioural_pass.
Audited 2026-10-08 · audit v0.4.1 · source sha
683538564abafull audit observations/trust-audit/mcp-server/drewburchfield__help-scout.json · Report an issue / request a re-scan05
Audit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-08 | 683538564aba | BLOCK | D | 68 | first audit |
06
Questions
What is the Help Scout MCP server?
MCP server for Help Scout - search conversations, customers, organizations, reports, and Docs with AI agents, plus opt-in writes for drafting replies and triage
What tools does Help Scout expose?
81 in total: 68 read-only, 10 that write, and 3 that can delete or overwrite (removeConversationTags, unassignConversation, unsnoozeConversation). Every one is listed on this page with its risk.
Is Help Scout safe to connect to an agent?
No — not without reading the findings first. The audit graded it D (68/100) and found 2 critical or high issues in the source. Each one is listed on this page with the file and line it is on. Separately from the audit: 3 of its tools can destroy data, so scope the token you give it to what you actually need.
What credentials does Help Scout need?
It reads HELPSCOUT_API_KEY, HELPSCOUT_APP_ID, HELPSCOUT_APP_SECRET, HELPSCOUT_CLIENT_SECRET and HELPSCOUT_DOCS_API_KEY from the environment. Give it a token scoped to the least it needs — an agent that can be talked into calling a tool can be talked into calling it with your credentials.
How does Help Scout run?
It speaks stdio, so it runs as a local process your client starts. It is published on npm as help-scout-mcp-server at 2.1.0.
How current is this page?
The grade is for one exact copy of the source (683538564aba), read on 2026-10-08. The repository is watched and re-audited when it changes.