FreeScout MCP Server
Manage FreeScout helpdesk tickets through MCP tools.
Fetch tickets by ID, number, or URL, optionally with conversation threads.
Analyze tickets for issue type, root cause, and suggested solutions.
Add internal notes to tickets.
Update ticket status (active/pending/closed/spam) and assignment, recording the acting user ID.
Create editable draft replies with Markdown converted to HTML and optional to/cc/bcc recipients.
Get ticket and customer context to personalize replies.
Search tickets by subject/textSearch (subject-only), customer email, ticket number, status, assignee, mailbox, state, created/updated time, pagination, and optional last-message preview.
List available mailboxes.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@FreeScout MCP Server Show me ticket #12345"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
FreeScout MCP Server
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
buildServerfactory serves both 2025-era and 2026 MCP stdio clients
Related MCP server: Xalantis MCP Server
v3 runtime
Requires Node.js 24 or newer.
Uses
@modelcontextprotocol/server2.x with Zod 4 input schemas.Serves both the 2025 legacy handshake and the 2026 stdio protocol from the same server factory.
Delivers
structuredContentfor stable analysis and write-operation results without declaring output schemas.Accepts FreeScout's successful
204 No Contentupdate 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):
{
"mcpServers": {
"freescout": {
"command": "npx",
"args": ["@verygoodplugins/mcp-freescout@latest"],
"env": {
"FREESCOUT_URL": "https://your-freescout-domain.com",
"FREESCOUT_API_KEY": "your-api-key-here"
}
}
}
}With Cursor IDE
Add this to your Cursor MCP settings:
Method 1: Via Cursor Settings UI
Open Cursor Settings (Cmd/Ctrl + ,)
Search for "MCP"
Click "Edit in settings.json"
Add the MCP server configuration
Method 2: Manual Configuration
Add this to your Cursor settings.json or create ~/.cursor/mcp.json:
{
"mcp": {
"servers": {
"freescout": {
"command": "npx",
"args": ["@verygoodplugins/mcp-freescout@latest"],
"env": {
"FREESCOUT_URL": "https://your-freescout-domain.com",
"FREESCOUT_API_KEY": "your-api-key-here"
}
}
}
}
}The server communicates only with the FreeScout instance configured in its environment.
Manual Installation (Alternative)
If you prefer to install and run the server locally:
Clone this repository:
git clone https://github.com/verygoodplugins/mcp-freescout.git
cd mcp-freescoutInstall dependencies:
npm installBuild the TypeScript code:
npm run buildConfigure your MCP client to use the local installation:
{
"mcpServers": {
"freescout": {
"command": "node",
"args": ["/path/to/mcp-freescout/dist/index.js"],
"env": {
"FREESCOUT_URL": "https://your-freescout-domain.com",
"FREESCOUT_API_KEY": "your-api-key-here"
}
}
}
}Usage with Other MCP Clients
Run the server directly:
npm startOr in development mode with auto-reload:
npm run devAvailable Tools
Core Ticket Operations
freescout_get_ticket
Fetch a FreeScout ticket with all its details and conversation threads.
Parameters:
ticket(required): Ticket ID, number, or FreeScout URLincludeThreads(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.
Natural Language Examples:
"Show me ticket #12345"
"Get the details for FreeScout ticket 34811"
"Fetch ticket https://support.example.com/conversation/12345"
"What's in ticket 12345?"
"Pull up the conversation for ticket #34811"
Example:
{
"ticket": "12345",
"includeThreads": true
}Example: Fetching a FreeScout ticket with conversation threads
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
freescout_add_note
Add an internal note to a ticket for team communication.
Parameters:
ticket(required): Ticket ID, number, or FreeScout URLnote(required): The note contentuserId(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 URLstatus(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 URLreplyText(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.
Markdown Support:
Bold text:
**text**or__text__ā textItalic text:
*text*or_text_ā textCode:`code`ācodeNumbered lists:
1. itemā proper ordered listsBullet lists:
- itemor* itemā proper unordered listsLine breaks: Double newlines create paragraphs, single newlines create line breaks
Workflow:
Use
freescout_get_ticket_contextto get customer info and ticket detailsLet the LLM craft a personalized reply using Markdown formatting
Use
freescout_create_draft_replyto 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
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 querystatus(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'"
"Look for tickets from customer 'victor@example.com'"
"Find all active tickets related to 'authentication'"
"Search for tickets in mailbox 1 containing 'bug report'"
"Find tickets in mailbox 2 with status pending"
Search Parameters (v2.0+):
textSearch(optional): Plain text search in ticket content/subjectassignee(optional): 'unassigned' | 'any' | user_id (number)status(optional): 'active' | 'pending' | 'closed' | 'spam' | 'all'state(optional): 'published' | 'deleted'mailboxId(optional): Filter by specific mailbox IDupdatedSince(optional): ISO date or relative time like "7d", "24h", "30m"createdSince(optional): ISO date or relative timetag(optional): Filter by a FreeScout tag name (requires the Tags module)page(optional): Page number for pagination (min: 1)pageSize(optional): Results per page (min: 1, max: 100)
Search Tips for AI Agents:
For unassigned tickets: Use
assignee: "unassigned"withstatus: "active"For recent tickets: Use
updatedSince: "7d"for last 7 daysFor specific user: Use
assignee: 123(user ID number)Status "active" = open/active tickets (NOT "open" - that's invalid)
Use freescout_get_mailboxes first if filtering by mailbox
Combine filters:
{ textSearch: "error", assignee: "unassigned", updatedSince: "24h" }
freescout_get_mailboxes
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, orreplace.ticket: ticket ID, number, or URL; required for updates and optional for listing. Without it,listreturns global tags.tags: tag names for an update.replacewith[]clears the ticket's tags;addandremoverequire at least one name.pageandpageSize: optional forlistonly;pageSizeis 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.
await mcp.callTool('freescout_tags', { action: 'add', ticket: '12345', tags: ['urgent'] });
await mcp.callTool('freescout_search_tickets', { tag: 'urgent', status: 'active' });Workflow Examples
Basic Ticket Analysis
// Analyze a ticket to understand the issue
await mcp.callTool('freescout_analyze_ticket', {
ticket: '12345',
});Complete Ticket Response Workflow
// 1. Analyze the ticket to understand the issue
const analysis = await mcp.callTool('freescout_analyze_ticket', {
ticket: '12345',
});
// 2. Get ticket context for personalized reply
const context = await mcp.callTool('freescout_get_ticket_context', {
ticket: '12345',
});
// 3. Create a draft reply directly in FreeScout
await 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 assignment
await mcp.callTool('freescout_update_ticket', {
ticket: '12345',
status: 'active',
assignTo: 1,
});
// 5. Add an internal note with findings
await 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
// 1. Get ticket context for personalized reply
const 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 sendingHandling Non-Bug Issues
// For third-party issues or feature requests
const 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
MCP client (2025 or 2026) ā stdio entry ā buildServer ā FreeScout API
ā
Ticket analysis
ā
Response to clientDevelopment
Running in Development Mode
npm run devRunning Tests
npm testLinting
npm run lintBuilding for Production
npm run buildConfiguration
Required Environment Variables
Variable | Description | Example |
| Your FreeScout instance URL |
|
| FreeScout API key |
|
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 |
| Default user ID for assignments |
|
Advanced Configuration Example
For more control, you can specify additional environment variables:
{
"mcpServers": {
"freescout": {
"command": "npx",
"args": ["@verygoodplugins/mcp-freescout@latest"],
"env": {
"FREESCOUT_URL": "https://support.example.com",
"FREESCOUT_API_KEY": "your-api-key",
"FREESCOUT_DEFAULT_USER_ID": "2"
}
}
}
}FreeScout API Setup
Log into your FreeScout instance as an administrator
Navigate to Manage ā API Keys
Create a new API key with appropriate permissions:
View conversations
Update conversations
Create threads (for notes)
Best Practices
Ticket Analysis
Always analyze tickets before implementing fixes
Check for third-party limitations before attempting fixes
Verify reproducibility with team notes
Customer Communication
Generate draft replies for review
Include fix descriptions in customer communications
Use explanatory replies for non-bug issues
Migration from v1.x to v2.0
Breaking Changes
The freescout_search_tickets tool has been redesigned with explicit filter parameters. The old query-string syntax is no longer supported.
Before (v1.x):
{
"query": "assignee:null",
"status": "active"
}After (v2.0):
{
"assignee": "unassigned",
"status": "active"
}For text search:
{
"textSearch": "authentication error",
"assignee": "unassigned",
"updatedSince": "7d"
}New Features to Adopt
Relative time filters: Use
"7d","24h","30m"instead of calculating ISO datesPagination: Add
pageandpageSizeparameters for large result setsStructured outputs: Stable analysis and write results include
structuredContent; tools do not declare output schemas
Automatic Retries
The server now automatically retries failed requests with exponential backoff. No configuration needed - it just works more reliably.
Troubleshooting
Common Issues
API Connection Errors
Verify your FreeScout URL includes the protocol (https://)
Check API key permissions in FreeScout
Ensure your FreeScout instance has API access enabled
New in v2.0: The server will automatically retry transient connection errors
Ticket Parsing Issues
The server accepts ticket IDs, numbers, and full URLs
URLs are automatically parsed to extract ticket IDs
Numeric inputs are treated as ticket IDs
Rate Limiting (429 Errors)
New in v2.0: The server automatically detects rate limits and backs off
Retry logic includes exponential backoff with jitter
No manual intervention needed
Contributing
Contributions are welcome! Please:
Fork the repository
Create a feature branch
Make your changes with tests
Submit a pull request
License
GPL-3.0 License - see LICENSE file for details
Support
For issues, questions, or suggestions:
Check the documentation
Built with š§” by Very Good Plugins
Roadmap
Batch ticket operations
Webhook support for real-time updates
Template system for common replies
Integration with CI/CD pipelines
Advanced search filters
Ticket metrics and analytics
Multi-language support for customer replies
Attachment handling
Custom field support
Automated testing integration
Available Tools
9 toolsfreescout_add_noteAdd Note to TicketB
Add an internal note to a FreeScout ticket
Inputs: note (required), ticket (required), userId.
freescout_analyze_ticketAnalyze FreeScout TicketBRead-only
Analyze a FreeScout ticket to determine issue type, root cause, and suggested solution
Inputs: ticket (required).
freescout_create_draft_replyCreate Draft ReplyA
Create a draft reply in FreeScout that can be edited before sending
Inputs: ticket (required), replyText (required), cc, to, +2 more.
freescout_get_mailboxesGet MailboxesBRead-only
Get list of available mailboxes
Inputs: no named parameters.
freescout_get_ticketGet FreeScout TicketCRead-only
Fetch and analyze a FreeScout ticket by ID or URL
Inputs: ticket (required), includeThreads.
freescout_get_ticket_contextGet Ticket ContextCRead-only
Get ticket context and customer info to help draft personalized replies
Inputs: ticket (required).
freescout_search_ticketsSearch FreeScout TicketsARead-only
Search for FreeScout tickets with explicit filter parameters. Text search is subject-only (FreeScout has no message-body full-text search): use subject (or its alias textSearch) to match the conversation subject, customerEmail to filter by the customer, and number to look up a single ticket. Use assignee: "unassigned" for unassigned tickets, or assignee: number for a specific user. Supports relative time filters like "7d", "24h". Use includeLastMessage: true to get a preview of the most recent message for each ticket.
Inputs: tag, page, state, number, +10 more.
freescout_tagsManage FreeScout TagsADestructive
List tags globally or on a ticket; add, remove, or replace ticket tags. Replace with an empty list clears all tags. Add/remove read the full existing tag list first; concurrent tag changes may be overwritten.
Inputs: action (required), page, tags, ticket, +1 more.
freescout_update_ticketUpdate Ticket Status/AssignmentCDestructive
Update ticket status and/or assignment
Inputs: ticket (required), status, userId, assignTo.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogā¦
TDQS
Scored across 9 tools
Three tools overlap around fetching/reading a ticket: freescout_get_ticket ('fetch and analyze'), freescout_get_ticket_context (context/customer info), and freescout_analyze_ticket (issue type/root cause), so an agent may hesitate on which to call. Most other tools (add_note, update_ticket, create_draft_reply, search_tickets, tags, mailboxes) are clearly distinct.
Names follow a consistent freescout_verb_noun pattern (get_ticket, add_note, update_ticket, create_draft_reply, search_tickets). The lone deviation is freescout_tags, a noun-only name that bundles list/add/remove/replace operations, which breaks the verb-based convention.
Nine tools is well within the ideal 3-15 range for a helpdesk integration, and each tool maps to a recognizable workflow step (read, search, annotate, update, reply, tag, mailbox).
Core read/annotate/update/tag flows are covered, but there is no tool to actually send a reply (only draft creation), no ticket creation, no thread/message listing, and no attachment handling. These are notable gaps that could leave agents at a dead end for real reply workflows.
Maintenance
Related MCP Connectors
Read and search tickets; reply, add internal notes and open tickets in Faveo Helpdesk.
Helpdesk tickets from your AI: find, reply, take, hold, complete ā within your own role. OAuth.
Work your HelpRabbit help desk: tickets, replies, customers, the AI agent and its knowledge.
Search, reply, tag, assign and report on ThriveDesk help desk conversations from your AI assistant.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables AI-powered ticket analysis and comprehensive Zendesk API integration via the Model Context Protocol, supporting both API token (CLI) and OAuth 2.1 (web) authentication modes.55190 npm5MIT

Xalantis MCP Serverofficial
AlicenseAqualityCmaintenanceEnables managing support tickets from Claude, Cursor, and other AI tools, including listing, creating, updating, and replying to tickets.633 npmMIT- AlicenseAqualityDmaintenanceEnables fetching and searching Freshdesk tickets, including details like conversations, attachments, and custom fields, via natural language queries.31MIT
- AlicenseAqualityBmaintenanceEnables AI agents to manage osTicket support tickets including listing, searching, reading, creating, updating, replying, deleting, managing subtickets, and downloading attachments.143MIT