@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 and workflow automation. This server provides tools to interact with FreeScout tickets, analyze issues, manage responses, and integrate with Git workflows.
gh) for GitHub integration (install from https://cli.github.com/)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 @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",
"WORKING_DIRECTORY": "${workspaceFolder}"
}
}
}
}
}
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",
"WORKING_DIRECTORY": "/path/to/your/project"
}
}
}
}
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)Natural Language Examples:
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:
freescout_get_mailboxesGet a list of all available mailboxes in your FreeScout instance.
Parameters: None
Natural Language Examples:
git_create_worktreeCreate a Git worktree for isolated ticket implementation.
Parameters:
ticketId (required): Ticket ID for the worktreebranchName (optional): Custom branch name (default: fix/freescout-{ticketId})baseBranch (optional): Base branch to create from (default: master)Natural Language Examples:
git_remove_worktreeRemove a Git worktree after work is complete.
Parameters:
ticketId (required): Ticket ID of the worktree to removeNatural Language Examples:
github_create_prCreate a GitHub pull request for the current branch. Automatically detects the repository from git remote.
Parameters:
title (required): PR titlebody (required): PR description/bodyticketId (optional): FreeScout ticket ID for reference (adds link to PR body)branch (optional): Branch name (defaults to current branch)baseBranch (optional): Base branch (default: master)draft (optional): Create as draft PR (default: false)Natural Language Examples:
Features:
gh) for authentication - no tokens required!gh installed and authenticated (gh auth login)freescout_implement_ticketworkflow automation: analyze ticket, create worktree, and prepare implementation plan.
Parameters:
ticket (required): Ticket ID, number, or FreeScout URLadditionalContext (optional): Additional context or implementation suggestionsautoCreateWorktree (optional): Automatically create Git worktree (default: true)Natural Language Examples:
Returns:
// Analyze a ticket to understand the issue
await mcp.callTool('freescout_analyze_ticket', {
ticket: '12345'
});
// 1. Start the implementation workflow
const plan = await mcp.callTool('freescout_implement_ticket', {
ticket: 'https://support.example.com/conversation/12345',
additionalContext: 'Consider backward compatibility'
});
// 2. After implementing the fix, create a GitHub PR
await mcp.callTool('github_create_pr', {
title: 'Fix: Validation error in checkout (FreeScout #12345)',
body: `## Summary
Fixes the validation error reported in the checkout process.
## Changes
- Fixed validation logic in checkout.js
- Added error handling for edge cases
## Testing
- Tested with various input combinations
- All existing tests pass`,
ticketId: '12345' // Automatically adds FreeScout link to PR
});
// 3. Get ticket context to craft a personalized reply
const context = await mcp.callTool('freescout_get_ticket_context', {
ticket: '12345'
});
// 4. Create a draft reply directly in FreeScout (LLM generates the content with Markdown)
await mcp.callTool('freescout_create_draft_reply', {
ticket: '12345',
replyText: `Hi ${context.customer.name},
Thank you for working through that validation issue with us! Your detailed report was really helpful.
I've just implemented a fix that addresses the checkout validation error you experienced. The fix includes:
1. **Improved validation logic** in the checkout process
2. **Better error handling** for edge cases
3. **Additional safeguards** to prevent similar issues
The fix has been submitted for review and will be included in the next plugin update. You'll receive the update through WordPress's automatic update system.
Thanks again for your patience and for helping us improve the plugin!
Best regards,
[Your name]`
});
// 5. Update ticket status and assignment
await mcp.callTool('freescout_update_ticket', {
ticket: '12345',
status: 'active',
assignTo: 1
});
// 6. Clean up the worktree after PR is created
await mcp.callTool('git_remove_worktree', {
ticketId: '12345'
});
// 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`
});
// 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 |
WORKING_DIRECTORY | Base directory for Git operations | Current working directory¹ |
GITHUB_REPO | GitHub repository (owner/repo) | Auto-detected using gh² |
¹ Note: Automatically uses the current project/workspace directory. Only set this if you need to work on a different directory.
² Note: The server automatically detects the GitHub repository using GitHub CLI (gh). Requires gh to be installed and authenticated (gh auth login). Only set GITHUB_REPO if you need to override the auto-detection.
For more control, you can specify additional environment variables:
{
"mcpServers": {
"freescout": {
"command": "npx @verygoodplugins/mcp-freescout@latest",
"env": {
"FREESCOUT_URL": "https://support.example.com",
"FREESCOUT_API_KEY": "your-api-key",
"FREESCOUT_DEFAULT_USER_ID": "2",
"WORKING_DIRECTORY": "/path/to/specific/project",
"GITHUB_REPO": "owner/repo"
}
}
}
}
Contributions are welcome! Please:
GPL-3.0 License - see LICENSE file for details
For issues, questions, or suggestions:
FAQs
MCP server for FreeScout ticket management and workflow automation
The npm package @verygoodplugins/mcp-freescout receives a total of 0 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.
Threat Research
/Security News
Cursor removed a malicious Claude Code 2.1.313 extension from its marketplace. Socket examines registry records and the initial claims about its distribution.
Security News
An OpenCode user faced harassment after reporting a free AI usage loophole, drawing a bitter backlash in a GitHub thread that has since been deleted.
Threat Research
/Security News
319 browser extensions installed by 13.4 million users hijack searches, capture queries, and collect referral payments from Yahoo and Bing.