@verygoodplugins/mcp-freescout
Advanced tools
MCP server for FreeScout ticket management and workflow automation
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.
McpServer and registerTool() patternsBreaking Changes:
McpServer class with structured outputsNew Features:
assignee, updatedSince, createdSince, page, pageSizeSee CHANGELOG.md for migration guide.
The easiest way to use this MCP server is with npx:
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"
}
}
}
}
Add this to your Cursor MCP settings:
Method 1: Via Cursor Settings UI
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"
}
}
}
}
}
That's it! The server will automatically use your current workspace directory for Git operations.
If you prefer to install and run the server locally:
git clone https://github.com/verygoodplugins/mcp-freescout.git
cd mcp-freescout
npm install
npm run build
{
"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"
}
}
}
}
Run the server directly:
npm start
Or in development mode with auto-reload:
npm run dev
freescout_get_ticketFetch 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)Natural Language Examples:
Example:
{
"ticket": "12345",
"includeThreads": true
}
Example: Fetching a FreeScout ticket with conversation threads
freescout_analyze_ticketAnalyze a ticket to determine issue type, root cause, and suggested solutions.
Parameters:
ticket (required): Ticket ID, number, or FreeScout URLNatural Language Examples:
Returns:
Example: Intelligent ticket analysis with issue classification
freescout_add_noteAdd 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:
freescout_update_ticketUpdate 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 toNatural Language Examples:
freescout_create_draft_replyCreate 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:
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.
Markdown Support:
**text** or __text__ → text*text* or _text_ → textCode: `code` → code1. item → proper ordered lists- item or * item → proper unordered listsWorkflow:
freescout_get_ticket_context to get customer info and ticket detailsfreescout_create_draft_reply to save the draft in FreeScout (Markdown automatically converted to HTML)Example: Draft reply workflow with personalized customer response
freescout_get_ticket_contextGet ticket context and customer information to help craft personalized replies.
Parameters:
ticket (required): Ticket ID, number, or FreeScout URLNatural Language Examples:
Returns:
freescout_search_ticketsSearch 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 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 timepage (optional): Page number for pagination (min: 1)pageSize (optional): Results per page (min: 1, max: 100)Search Tips for AI Agents:
assignee: "unassigned" with status: "active"updatedSince: "7d" for last 7 daysassignee: 123 (user ID number){ textSearch: "error", assignee: "unassigned", updatedSince: "24h" }freescout_get_mailboxesGet a list of all available mailboxes in your FreeScout instance.
Parameters: None
Natural Language Examples:
// Analyze a ticket to understand the issue
await mcp.callTool('freescout_analyze_ticket', {
ticket: '12345',
});
// 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}`,
});
// 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 sending
// For third-party issues or feature requests
const reply = await mcp.callTool('freescout_draft_reply', {
ticket: '12345',
fixDescription: 'This is a limitation of the Elementor plugin that we cannot override.',
isExplanatory: true,
});
FreeScout API Client (freescout-api.ts)
Ticket Analyzer (ticket-analyzer.ts)
MCP Server (index.ts)
User Request → MCP Server → FreeScout API → Ticket Analyzer
↓ ↓
Git Operations Analysis Results
↓ ↓
Worktree Management Customer Reply
↓ ↓
Response → User
npm run dev
npm test
npm run lint
npm run build
| Variable | Description | Example |
|---|---|---|
FREESCOUT_URL | Your FreeScout instance URL | https://support.example.com |
FREESCOUT_API_KEY | FreeScout API key | your-api-key-here |
| Variable | Description | Default |
|---|---|---|
FREESCOUT_DEFAULT_USER_ID | Default user ID for assignments | 1 |
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"
}
}
}
}
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"
}
"7d", "24h", "30m" instead of calculating ISO datespage and pageSize parameters for large result setsstructuredContent for better integrationThe server now automatically retries failed requests with exponential backoff. No configuration needed - it just works more reliably.
Contributions are welcome! Please:
GPL-3.0 License - see LICENSE file for details
For issues, questions, or suggestions:
Built with 🧡 by Very Good Plugins
FAQs
MCP server for FreeScout ticket management and workflow automation
The npm package @verygoodplugins/mcp-freescout receives a total of 143 weekly downloads. As such, @verygoodplugins/mcp-freescout popularity was classified as not popular.
We found that @verygoodplugins/mcp-freescout demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Research
/Security News
A Twitch browser extension on Chrome and Firefox forwards users’ live OAuth session tokens through proxies controlled by a Russian bot service.
Security News
Anthropic found biased reasoning and recklessness drove Claude Mythos 5 to publish malware on PyPI and compromise a security vendor.
Research
/Security News
Malicious Chrome and Firefox extensions target Axiom Trade and Padre users, stealing session tokens and wallet data.