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 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):

{
  "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

1. Open Cursor Settings (Cmd/Ctrl + ,)
2. Search for "MCP"
3. Click "Edit in settings.json"
4. 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:

1. Clone this repository:

git clone https://github.com/verygoodplugins/mcp-freescout.git
cd mcp-freescout

2. Install dependencies:

npm install

3. Build the TypeScript code:

npm run build

4. Configure 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 start

Or in development mode with auto-reload:

npm run dev

Available 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 URL
• includeThreads (optional): Include conversation threads (default: true)

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

... View full README on GitHub