Help Scout CLI

A CLI for Help Scout's Mailbox API 2.0. JSON output by default for LLM and automation workflows.

Installation

bun install -g @stephendolan/helpscout-cli

# Or run without installing
bunx @stephendolan/helpscout-cli conversations list

Linux: Requires libsecret for keychain storage (apt install libsecret-1-dev), or use environment variables.

Authentication

Create an OAuth app at Help Scout > Your Profile > My Apps.

helpscout auth login --app-id YOUR_APP_ID --app-secret YOUR_APP_SECRET
helpscout auth status
helpscout auth logout
helpscout auth refresh                          # Refresh access token

Or use environment variables: HELPSCOUT_APP_ID, HELPSCOUT_APP_SECRET, HELPSCOUT_MAILBOX_ID

Commands

Conversations

helpscout conversations list
helpscout conversations list --status active --mailbox 123 --tag urgent
helpscout conversations list -q 'status:open customer:[email protected]'
helpscout conversations list --summary

helpscout conversations view 456
helpscout conversations threads 456
helpscout conversations threads 456 --type customer  # Filter by type
helpscout conversations threads 456 --html          # HTML output
helpscout conversations threads 456 --include-notes
helpscout conversations attachments download 456 789
helpscout conversations attachments download 456 789 --output ./invoice.pdf
helpscout conversations attachments download 456 789 --output ./downloads/
helpscout conversations attachments download 456 789 --force
helpscout conversations status 456 closed
helpscout conversations reply 456 --text "Thanks for reaching out!"
helpscout conversations note 456 --text "Internal note"
helpscout conversations add-tag 456 urgent
helpscout conversations remove-tag 456 urgent
helpscout conversations delete 456

Customers

helpscout customers list
helpscout customers list --first-name John
helpscout customers view 789
helpscout customers create --first-name John --last-name Doe --email [email protected]
helpscout customers update 789 --organization "Acme Corp"
helpscout customers delete 789

Users

helpscout users list
helpscout users list --email [email protected]
helpscout users list --mailbox 123 --page 2
helpscout users view 456

User responses include the mention handle when Help Scout returns one. Use @mention in Help Scout thread bodies to mention teammates.

Tags, Workflows, Mailboxes

helpscout tags list
helpscout tags view 123

helpscout workflows list
helpscout workflows list --type manual
helpscout workflows run 123 --conversations 456,789
helpscout workflows activate 123
helpscout workflows deactivate 123

helpscout mailboxes list
helpscout mailboxes view 123
helpscout mailboxes set-default 123
helpscout mailboxes get-default
helpscout mailboxes clear-default

MCP Server

Run as an MCP server for AI agent integration:

helpscout mcp

The MCP server exposes:

• Typed tools for Help Scout search, full conversation detail, full conversation thread history, attachment downloads, mailbox/customer/user lookup, and safe draft-note/status mutations
• get_conversation accepts internal conversation IDs or visible ticket numbers like #12345
• get_conversation_threads returns all Help Scout thread types by default, including notes, workflow events, status events, and other system events returned by Help Scout
• download_attachment saves a conversation attachment to disk, using the Help Scout filename by default and requiring force before overwriting existing files
• update_conversation_status safely changes ticket status, with open normalized to Help Scout's active status
• create_note adds private notes and can optionally set the ticket status, such as closing no-action tickets
• User lookup tools expose Help Scout mention handles for composing @mention references
• Resource templates for helpscout://conversation/{conversationId}, helpscout://customer/{customerId}, and helpscout://user/{userId}
• Prompt templates for summarize_ticket and draft_reply

Read-only tools include MCP annotations so hosts can distinguish them from mutating tools, and core read/query tools return structured outputs alongside readable JSON text.

Options

| Flag | Description | |------|-------------| | -c, --compact | Minified JSON output | | -p, --plain | Strip HTML from body fields | | -f, --fields <fields> | Include only specified fields | | --include-metadata | Include _links and _embedded |

Examples

helpscout conversations list | jq '.conversations[].subject'
helpscout conversations list --fields id,subject

Errors: {"error": {"name": "...", "detail": "...", "statusCode": 400}}

References

• Help Scout API Docs
• Search Filters

License

MIT