FreeScout ticket management with AI-powered analysis, search filters, and structured outputs.
FreeScout MCP Server (io.github.verygoodplugins/mcp-freescout)
An MCP (Model Context Protocol) server for FreeScout helpdesk ticket management. It provides tools to interact with FreeScout tickets, analyze issues, and manage customer responses, including automated analysis, draft reply generation, and advanced search filtering.
๐ ๏ธ Key Features
Ticket management: fetch, analyze, and update FreeScout tickets
Intelligent analysis: determine issue type, root cause, and solutions
Draft responses: generate customer replies based on ticket analysis
Advanced search: first-class filter parameters with relative time support (e.g., โ7dโ, โ24hโ)
๐ Use Cases
Analyze FreeScout tickets to categorize issues and suggest solutions
Produce structured customer responses for support workflows
Query tickets using filter parameters and relative time ranges
โก Developer Benefits
Provides structured outputs for ticket analysis and response drafting
Supports search filters for targeted ticket retrieval
Exposes 8 tools for ticket interaction and related tasks
โ ๏ธ Limitations
The provided description does not include authentication, deployment details, or tool list specifics beyond the features excerpt.
An MCP (Model Context Protocol) server for FreeScout helpdesk ticket management. This server provides tools to interact with FreeScout tickets, analyze issues, and manage customer responses.
Features
๐ซ Ticket Management: Fetch, analyze, and update FreeScout tickets
๐ Intelligent Analysis: Automatically analyze tickets to determine issue type, root cause, and solutions
๐ฌ Draft Responses: Generate customer replies based on ticket analysis
๐ Advanced Search: First-class filter parameters with relative time support ("7d", "24h")
๐ Type Safety: Full Zod schema validation with structured outputs
๐ Reliability: Automatic retry logic with exponential backoff for transient failures
โก Protocol-ready stdio: A fresh buildServer factory serves both 2025-era and 2026 MCP stdio clients
v3 runtime
Requires Node.js 24 or newer.
Uses @modelcontextprotocol/server 2.x with Zod 4 input schemas.
Serves both the 2025 legacy handshake and the 2026 stdio protocol from the same server factory.
Delivers structuredContent for stable analysis and write-operation results without declaring output schemas.
Accepts FreeScout's successful 204 No Content update responses and records the user ID that initiated a ticket update.
Installation
Prerequisites
Node.js 24 or higher
FreeScout instance with API access enabled
Quick Start (Recommended)
The easiest way to use this MCP server is with npx:
With Claude Desktop
Add this to your Claude Desktop settings (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
Fetch a FreeScout ticket with all its details and conversation threads.
Parameters:
ticket (required): Ticket ID, number, or FreeScout URL
includeThreads (optional): Include conversation threads (default: true). When false, threads are omitted from the result, though FreeScout may still include them in the upstream HTTP response.
Example: Fetching a FreeScout ticket with conversation threads
FreeScout ticket details and conversation threads displayed in Cursor chat interface
freescout_analyze_ticket
Analyze a ticket to determine issue type, root cause, and suggested solutions.
Parameters:
ticket (required): Ticket ID, number, or FreeScout URL
Natural Language Examples:
"Analyze ticket #12345"
"What kind of issue is ticket 34811?"
"Can you analyze this ticket and tell me if it's a bug?"
"Examine ticket #12345 and determine the root cause"
"Is this ticket a bug or feature request?"
Returns:
Customer information
Issue description and classification
Code snippets and error messages
Reproducibility status
Root cause analysis
Bug vs feature request vs third-party issue determination
Example: Intelligent ticket analysis with issue classification
Ticket analysis showing issue type, root cause, and implementation recommendations
freescout_add_note
Add an internal note to a ticket for team communication.
Parameters:
ticket (required): Ticket ID, number, or FreeScout URL
note (required): The note content
userId (optional): User ID for the note (defaults to env setting)
Natural Language Examples:
"Add a note to ticket #12345 saying 'Reproduced on staging'"
"Leave an internal note on this ticket"
"Add a team note: 'Customer confirmed fix works'"
"Note on ticket 34811: 'Escalating to development team'"
"Add internal documentation to this ticket"
freescout_update_ticket
Update ticket status and/or assignment.
Parameters:
ticket (required): Ticket ID, number, or FreeScout URL
status (optional): New status ('active', 'pending', 'closed', 'spam')
assignTo (optional): User ID to assign the ticket to
Natural Language Examples:
"Close ticket #12345"
"Mark ticket 34811 as pending"
"Assign this ticket to user ID 2"
"Set ticket status to active"
"Update ticket #12345 status to closed and assign to user 1"
freescout_create_draft_reply
Create a draft reply in FreeScout that can be edited before sending. This tool lets the LLM generate the reply content and saves it directly to FreeScout as a draft. Automatically converts Markdown formatting to HTML for proper display in FreeScout.
Parameters:
ticket (required): Ticket ID, number, or FreeScout URL
replyText (required): The draft reply content (generated by the LLM, supports Markdown formatting)
userId (optional): User ID creating the draft (defaults to env setting)
to (optional): List of TO recipients. Omit to preserve existing recipients; pass [] to clear.
cc (optional): List of CC recipients. Omit to preserve existing recipients; pass [] to clear.
bcc (optional): List of BCC recipients. Omit to preserve existing recipients; pass [] to clear.
Natural Language Examples:
"Create a draft reply for ticket #12345"
"Draft a customer response for this ticket"
"Generate and save a draft reply explaining the fix"
"Write a draft response to the customer for ticket 34811"
"Create a draft reply thanking the customer and explaining the solution"
If recipient fields are omitted, the server preserves the current conversation recipients from FreeScout when available. If FreeScout does not expose existing to recipients on the conversation, its normal default customer recipient behavior is preserved.
The result includes draftId when FreeScout returns the new thread ID. If creation succeeds without an ID, draftId is null; the draft was still created and should not be retried solely to obtain its ID.
Line breaks: Double newlines create paragraphs, single newlines create line breaks
Workflow:
Use freescout_get_ticket_context to get customer info and ticket details
Let the LLM craft a personalized reply using Markdown formatting
Use freescout_create_draft_reply to save the draft in FreeScout (Markdown automatically converted to HTML)
Review and edit the draft in FreeScout before sending
Example: Draft reply workflow with personalized customer response
Draft reply generation showing personalized customer message with ticket context
Draft reply automatically saved to FreeScout
freescout_get_ticket_context
Get ticket context and customer information to help craft personalized replies.
Parameters:
ticket (required): Ticket ID, number, or FreeScout URL
Natural Language Examples:
"Get context for ticket #12345 to write a reply"
"I need customer info and ticket details for drafting a response"
"Gather context for this ticket so I can write a personalized reply"
"Pull customer information and issue details for ticket 34811"
"Get ticket context to help craft a customer response"
Returns:
Customer name and email
Ticket subject and status
Issue description and analysis
Recent customer and team messages
Analysis results (bug vs feature vs third-party issue)
Thread dates accept FreeScout's createdAt and the legacy created_at spelling. Messages without a usable timestamp remain in context with date: null; teamMessagesOmittedCount reports when the three-message context limit excludes entries. When a search preview encounters undated customer or agent messages, undatedMessageCount indicates that its dated lastMessage may not be the most recent.
freescout_search_tickets
Search for tickets across your FreeScout instance.
Parameters:
query (required): Search query
status (optional): Filter by status ('active', 'pending', 'closed', 'spam', 'all')
mailboxId (optional): Filter by specific mailbox ID (searches all mailboxes if not specified)
Natural Language Examples:
"Search for tickets containing 'OAuth error'"
"Find all pending tickets with 'HighLevel' in them"
"Search for closed tickets about 'plugin conflicts'"
Get a list of all available mailboxes in your FreeScout instance.
Parameters:
None
Natural Language Examples:
"Show me all available mailboxes"
"List the mailboxes in FreeScout"
"What mailboxes are configured?"
"Get mailbox information"
freescout_tags
List tags or manage the tags on a ticket. This tool requires FreeScout's Tags module and is marked as potentially destructive because it can replace or clear tags.
action: list, add, remove, or replace.
ticket: ticket ID, number, or URL; required for updates and optional for listing. Without it, list returns global tags.
tags: tag names for an update. replace with [] clears the ticket's tags; add and remove require at least one name.
page and pageSize: optional for list only; pageSize is at most 100.
Add and remove first read every page of the ticket's tags and refuse to write if the list is incomplete. FreeScout replaces the full list without a conditional update, so concurrent changes made between the read and write can still be overwritten. Replacing with an unknown tag name creates that tag in FreeScout.
// Analyze a ticket to understand the issueawait mcp.callTool('freescout_analyze_ticket', {
ticket: '12345',
});
Complete Ticket Response Workflow
javascript
// 1. Analyze the ticket to understand the issueconst analysis = await mcp.callTool('freescout_analyze_ticket', {
ticket: '12345',
});
// 2. Get ticket context for personalized replyconst context = await mcp.callTool('freescout_get_ticket_context', {
ticket: '12345',
});
// 3. Create a draft reply directly in FreeScoutawait mcp.callTool('freescout_create_draft_reply', {
ticket: '12345',
replyText: `Hi ${context.customer.name},
Thank you for reaching out! Based on my analysis, I can see that ${analysis.issueDescription}.
Here's what I found:
1. **Issue Type**: ${analysis.isBug ? 'Bug' : 'Configuration/Feature Request'}
2. **Root Cause**: ${analysis.rootCause || 'Under investigation'}
I'll look into this and get back to you shortly with a solution.
Best regards,
[Your name]`,
cc: ['billing@example.com'],
});
// 4. Update ticket status and assignmentawait mcp.callTool('freescout_update_ticket', {
ticket: '12345',
status: 'active',
assignTo: 1,
});
// 5. Add an internal note with findingsawait mcp.callTool('freescout_add_note', {
ticket: '12345',
note: `Analysis complete:
- Is Bug: ${analysis.isBug}
- Third-party Issue: ${analysis.isThirdPartyIssue}
- Root Cause: ${analysis.rootCause}`,
});
Draft Reply Workflow
javascript
// 1. Get ticket context for personalized replyconst context = await mcp.callTool('freescout_get_ticket_context', {
ticket: '34811',
});
// 2. Create draft reply in FreeScout (LLM crafts the content)await mcp.callTool('freescout_create_draft_reply', {
ticket: '34811',
replyText: `Hi ${context.customer.name},
Thank you for reporting the HighLevel OAuth authorization issue! Your experience with the EngageBay LiveChat plugin conflict has been really valuable.
Based on what we learned from your case, I've added a new plugin conflict detection system to WP Fusion. In the next update (v3.46.7), users will see:
๐ **Plugin Conflict Detection**
- Automatic detection of known conflicting plugins
- Warning messages before HighLevel authorization
- Clear guidance when conflicts are detected
This should prevent the confusion you experienced and help other users avoid similar issues.
The update should be available within the next few weeks. Thanks for your patience and for helping us improve the plugin!
Best regards,
Jack`,
to: ['primary@example.com'],
cc: ['teammate@example.com'],
});
// The draft is now saved in FreeScout and can be reviewed/edited before sending
Handling Non-Bug Issues
javascript
// For third-party issues or feature requestsconst reply = await mcp.callTool('freescout_create_draft_reply', {
ticket: '12345',
replyText: 'This is a limitation of the Elementor plugin that we cannot override.',
});
Architecture
Components
FreeScout API Client (freescout-api.ts)
Handles all API communication with FreeScout
Manages authentication and request formatting
Provides ticket parsing utilities
Ticket Analyzer (ticket-analyzer.ts)
Intelligent ticket content analysis
Issue classification (bug vs feature vs configuration)
Code snippet and error extraction
Root cause determination
MCP Server (index.ts)
Tool registration and request handling
Fresh server factory for each stdio connection
Response formatting and error handling
Data Flow
code
MCP client (2025 or 2026) โ stdio entry โ buildServer โ FreeScout API
โ
Ticket analysis
โ
Response to client
Development
Running in Development Mode
bash
npm run dev
Running Tests
bash
npm test
Linting
bash
npm run lint
Building for Production
bash
npm run build
Configuration
Required Environment Variables
Variable
Description
Example
FREESCOUT_URL
Your FreeScout instance URL
https://support.example.com
FREESCOUT_API_KEY
FreeScout API key
your-api-key-here
The server starts and lists its tools without these variables. They are checked
when a tool is called, and a call made without them returns an error that names
the missing variables.
Optional Environment Variables
Variable
Description
Default
FREESCOUT_DEFAULT_USER_ID
Default user ID for assignments
1
Advanced Configuration Example
For more control, you can specify additional environment variables: