Help Scout MCP Server
Help Scout MCP Server - Connect Claude and other AI assistants to your Help Scout data with enterprise-grade security and advanced search capabilities.
Power your agent
Yayıncının kendi komutu. PlugMCP uç noktası değildir.
Host a copy with our keys and logs.
npx -y @gravitykit/[email protected]Claude Code'un yerel komutlar için kurulum bağlantısı yok. Aşağıdaki komutu kopyalayın ve bir terminalde çalıştırın.
claude mcp add gravitykit-help-scout-mcp -- npx -y @gravitykit/help-scout-mcp@2.4.4Bir terminalde çalıştırın.
{ "mcpServers": { "gravitykit-help-scout-mcp": { "command": "npx", "args": [ "-y", "@gravitykit/[email protected]" ] } }}claude_desktop_config.json
Uzak URL mi, yoksa makinenizde bir komut mu? İki kurulum arasındaki fark
PlugMCP’de çalıştır
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
BaşlatYayıncıdan
Help Scout MCP Server - Connect Claude and other AI assistants to your Help Scout data with enterprise-grade security and advanced search capabilities.
Help Scout MCP server: search conversations, fetch transcripts, browse docs, and pull reports — all from Claude or any MCP client
Note: This is a fork of the original help-scout-mcp by Drew Burchfield.
HELPSCOUT_APP_ID and HELPSCOUT_APP_SECRETNote: The MCPB extension bundles all dependencies, so no local Node.js installation needed for Claude Desktop users.
The fastest way to get started — just ask Claude to install it:
claude "Install the @gravitykit/help-scout-mcp MCP server"
Claude Code will add it to your project's .mcp.json automatically. When prompted, provide your Help Scout App ID and App Secret.
You can also add it manually:
claude mcp add helpscout -- npx @gravitykit/help-scout-mcp
Then set your credentials in .mcp.json:
{
"mcpServers": {
"helpscout": {
"command": "npx",
"args": ["@gravitykit/help-scout-mcp"],
"env": {
"HELPSCOUT_APP_ID": "your-app-id",
"HELPSCOUT_APP_SECRET": "your-app-secret"
}
}
}
}
Easiest setup using MCP Bundles - no configuration needed:
.mcpb file from releases{
"mcpServers": {
"helpscout": {
"command": "npx",
"args": ["@gravitykit/help-scout-mcp"],
"env": {
"HELPSCOUT_APP_ID": "your-app-id",
"HELPSCOUT_APP_SECRET": "your-app-secret"
}
}
}
}
HELPSCOUT_APP_ID="your-app-id" \
HELPSCOUT_APP_SECRET="your-app-secret" \
npx @gravitykit/help-scout-mcp
This method is recommended for production use and provides automatic token refresh.
Why Client Credentials? MCP servers are backend applications that run without user interaction. We use the Client Credentials flow (not Authorization Code flow) because:
https://example.com (required field but not used for server apps)Select the scopes your app needs:
Note: Only select the scopes you actually need for security best practices.
Set these environment variables:
export HELPSCOUT_APP_ID="your-app-id-here"
export HELPSCOUT_APP_SECRET="your-app-secret-here"
Or add to your .env file:
HELPSCOUT_APP_ID=your-app-id-here
HELPSCOUT_APP_SECRET=your-app-secret-here
# Test with environment variables
HELPSCOUT_APP_ID="your-app-id" \
HELPSCOUT_APP_SECRET="your-app-secret" \
npx @gravitykit/help-scout-mcp
# Or if using .env file
npx @gravitykit/help-scout-mcp
HELPSCOUT_DOCS_API_KEY=your-docs-api-keyImportant Notes:
Set
HELPSCOUT_DISABLE_DOCS=trueto hide all Docs tools if you don't use Help Scout Docs.
helpscout://inboxes - List all accessible inboxeshelpscout://conversations - Search conversations with filtershelpscout://threads - Get thread messages for a conversationhelpscout://clock - Current server timestamphelpscout-docs://sites - List all documentation siteshelpscout-docs://collections - List collections with filteringhelpscout-docs://categories - List categories in a collectionhelpscout-docs://articles - Get articles with full contentTip:
searchConversationshandles listing, keyword search, and structured search — use different parameters for different needs.
// Best for "show me recent tickets" - omit query parameter
searchConversations({
limit: 25,
sort: "createdAt",
order: "desc"
})
// Best for "find tickets about X" - uses keyword search
searchConversations({
searchTerms: ["urgent", "billing"],
timeframeDays: 60,
inboxId: "256809"
})
// Search in message bodies and subjects
searchConversations({
searchTerms: ["refund", "cancellation"],
searchIn: ["both"],
timeframeDays: 30
})
// Customer organization search (structured fields)
searchConversations({
emailDomain: "company.com",
contentTerms: ["integration", "API"],
status: "active"
})
// Advanced query syntax support
searchConversations({
query: "(body:\"urgent\" OR subject:\"emergency\") AND tag:\"escalated\"",
status: "active"
})
// List all documentation sites
listDocsSites({
page: 1
})
// Get articles in a collection
listDocsArticles({
collectionId: "123456",
status: "published",
sort: "popularity"
})
// Get full article content
getDocsArticle({
articleId: "789012"
})
// Update an article
updateDocsArticle({
articleId: "789012",
name: "Updated Article Title",
text: "<p>New article content</p>"
})
// Create a draft reply (default, safe)
createReply({
conversationId: "98234",
text: "<p>Thanks for reaching out! Let me look into this.</p>",
customer: { email: "[email protected]" }
})
// Create a published reply (requires HELPSCOUT_ALLOW_SEND_REPLY=true)
createReply({
conversationId: "98234",
text: "<p>Your export issue has been resolved.</p>",
customer: { id: 67890 },
draft: false,
status: "closed"
})
HTML in replies is automatically formatted for Help Scout's native editor:
<p> tags converted to <br><br> line breaks<pre> blocks converted to <div> (Help Scout strips <pre>)<code> tags get class="inline-code" for stylingHELPSCOUT_REPLY_SPACING// Get a conversation by ID
getConversation({
conversationId: "98234"
})
// Get a conversation with embedded threads
getConversation({
conversationId: "98234",
embed: ["threads"]
})
// Create a new conversation
createConversation({
subject: "New support request",
type: "email",
mailboxId: 256809,
customer: { email: "[email protected]" },
threads: [{ type: "customer", text: "I need help with my account." }]
})
// Update a conversation's status and tags
updateConversation({
conversationId: "98234",
status: "pending",
tags: ["billing", "priority"]
})
// Reassign a conversation
updateConversation({
conversationId: "98234",
assignTo: 12345
})
// Single call: get latest tickets with full message transcripts
searchConversations({
includeTranscripts: true,
limit: 10
})
// Search with transcripts for AI analysis
searchConversations({
searchTerms: ["billing", "refund"],
includeTranscripts: true,
transcriptMaxMessages: 5
})
// Get email conversation report with comparison
getReport({
type: "email",
start: "2024-01-01T00:00:00Z",
end: "2024-01-31T23:59:59Z",
previousStart: "2023-12-01T00:00:00Z",
previousEnd: "2023-12-31T23:59:59Z",
mailboxes: ["123456"],
viewBy: "week"
})
// Get user performance report
getReport({
type: "user",
start: "2024-01-01T00:00:00Z",
end: "2024-01-31T23:59:59Z",
user: "789012",
types: ["email", "chat"],
officeHours: true
})
// Get happiness report with filters
getReport({
type: "happiness",
start: "2024-01-01T00:00:00Z",
end: "2024-01-31T23:59:59Z",
rating: ["great", "ok"],
mailboxes: ["123456"],
viewBy: "day"
})
// Get company-wide analytics
getReport({
type: "company",
start: "2024-01-01T00:00:00Z",
end: "2024-01-31T23:59:59Z",
viewBy: "month"
})
The server provides three response modes to optimize token usage and support different use cases.
Every conversation and thread is stripped to just the fields that matter: id, number, subject, status, preview, assignee, customer, tags, and dates. All Help Scout API cruft (_links, _embedded, closedByUser, source metadata, tag styles, photo URLs, etc.) is removed automatically.
{
"id": 98234,
"number": 14052,
"subject": "Can't export to CSV",
"status": "active",
"preview": "When I click Export, nothing happens...",
"assignee": { "first": "Rafael", "last": "Smith" },
"customer": { "first": "Maria", "last": "Garcia", "email": "[email protected]" },
"tags": ["tech-support"],
"createdAt": "2026-02-14T10:30:00Z"
}
verbose: true)Returns the full, raw Help Scout API response objects. Useful for debugging or when you need a specific field that slim mode strips out. This behavior is still supported, but verbose is no longer advertised in tool schemas; the default public surface stays slim.
{
"id": 98234,
"number": 14052,
"subject": "Can't export to CSV",
"status": "active",
"state": "published",
"type": "email",
"preview": "When I click Export, nothing happens...",
"mailboxId": 256809,
"assignee": { "id": 12345, "first": "Rafael", "last": "Smith", "email": "[email protected]" },
"createdBy": { "id": 67890, "type": "customer" },
"customer": { "id": 67890, "first": "Maria", "last": "Garcia", "email": "[email protected]" },
"tags": [{ "id": 13974028, "name": "tech-support", "color": "#929292" }],
"closedBy": null,
"closedByUser": null,
"source": { "type": "email", "via": "customer" },
"_links": { "self": { "href": "..." }, "threads": { "href": "..." }, "mailbox": { "href": "..." } },
"_embedded": { "threads": { "_links": { "..." } } }
}
Purpose-built for AI analysis and summarization. Available in two ways:
getThreads with format: "transcript"searchConversations with includeTranscripts: trueTranscripts:
source.type: "support-agent-ai") and unsent drafts (state: "draft") by default. Set excludeDrafts: false on getThreads to include all threads.REDACT_MESSAGE_CONTENT privacy settingtranscriptMaxMessages, default 10)Before — summarizing 10 tickets required 11 API calls:
// 1. Search for conversations
const results = searchConversations({ limit: 10 })
// 2. Fetch threads for each conversation individually
for (const conversation of results) {
getThreads({ conversationId: conversation.id, format: "transcript" })
}
After — a single call:
searchConversations({ includeTranscripts: true, limit: 10 })
Returns conversations with inline transcript arrays:
{
"results": [
{
"id": 98234,
"subject": "Can't export to CSV",
"status": "active",
"customer": { "first": "Maria" },
"transcript": [
{ "role": "customer", "from": "Maria", "date": "...", "body": "When I click Export, nothing happens..." },
{ "role": "staff", "from": "Rafael", "date": "...", "body": "Could you try disabling your browser extensions?" }
]
}
],
"includeTranscripts": true,
"transcriptMaxMessages": 10
}
Design notes:
includeTranscripts is true and no limit is specified, defaults to 10 conversations (not 50)Promise.allSettled — one failed transcript doesn't break the responsetranscript: null and a transcriptError fieldgetThreads or searchConversationsThe MCP server includes intelligent natural language processing for Help Scout Docs sites and collections:
// These all work to find GravityKit articles:
listDocsCollections({ query: "GravityKit" })
getSiteCollections({ query: "GravityKit" })
searchDocsArticles({ query: "GravityKit help articles" })
// Natural language site queries:
listDocsCollections({ query: "GravityKit" }) // Find GravityKit site
getSiteCollections({ query: "TrustedLogin site" }) // Get TrustedLogin collections
listDocsSites({ query: "gravity" }) // Find sites matching "gravity"
The system matches sites and collections using:
Set default site and collection for queries without specific context:
export HELPSCOUT_DEFAULT_DOCS_SITE_ID="your-site-id"
export HELPSCOUT_DEFAULT_DOCS_COLLECTION_ID="your-collection-id"
listDocsSites to see all Docs sites (with optional NLP filtering)getSiteCollections to get collections for a specific site using NLPWorks with any Model Context Protocol (MCP) compatible client:
Primary Platform: Claude Desktop with full MCPB and manual configuration support
Since this server follows the MCP standard, it automatically works with any current or future MCP-compatible client.
REDACT_MESSAGE_CONTENTSee GitHub Releases for version history and release notes.
# Quick start
git clone https://github.com/GravityKit/help-scout-mcp.git
cd help-scout-mcp
npm install && npm run build
# Create .env file with your credentials (OAuth2)
echo "HELPSCOUT_APP_ID=your-app-id" > .env
echo "HELPSCOUT_APP_SECRET=your-app-secret" >> .env
# Start the server
npm start
Authentication Failed
# Verify your credentials
echo $HELPSCOUT_APP_ID
echo $HELPSCOUT_APP_SECRET
# Test with curl
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"
Connection Timeouts
api.helpscout.netHTTP_SOCKET_TIMEOUT environment variableRate Limiting
Empty Search Results
searchConversations without searchTerms for listing, with searchTerms for keyword search[""] in searchTermsIf you're getting "Unknown URL" errors when accessing reports:
1. Verify Your Plan
2. Check OAuth App Permissions
3. Feature Availability
4. API Response Debugging
# Enable debug logging to see actual API responses
LOG_LEVEL=debug npx @gravitykit/help-scout-mcp
Enable debug logging to troubleshoot issues:
LOG_LEVEL=debug npx @gravitykit/help-scout-mcp
If you're still having issues:
We welcome contributions! Here's how to get started:
git clone https://github.com/GravityKit/help-scout-mcp.git
cd help-scout-mcp
npm install
# Run tests
npm test
# Type checking
npm run type-check
# Linting
npm run lint
# Build for development
npm run build
# Start development server
npm run dev
npm test)npm run type-check)npm run lint)When reporting bugs, please include:
We'd love to hear your ideas! Please open an issue describing:
MIT License - see LICENSE file for details.
Need help? Open an issue or check our documentation.
Help Scout MCP server: search conversations, fetch transcripts, browse docs, and pull reports — all from Claude or any MCP client
{ "mcpServers": { "gravitykit-help-scout-mcp": { "command": "npx", "args": [ "-y", "@gravitykit/[email protected]" ] } }}Araçlar
Henüz araç listesi yok. Uzak sunucular ilk sağlık kontrolünden sonra bir liste alır.
SSS
Bu sayfadan Cursor, Claude Desktop, Claude Code veya VS Code için stdio yapılandırmasını kopyalayın. PlugMCP proxy'sini değil, yayıncının kurulumunu kullanır.
Bu kayıtta gerekli bir ortam değişkeni listelenmiyor.
@gravitykit/help Scout yerel olarak stdio üzerinden çalışır.
Son kontrol: 2026-11-16. Help Scout MCP server: search conversations, fetch transcripts, browse docs, and pull reports — all from Claude or any MCP client