MCP FreeScout MCP server

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/claudedesktopconfig.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

1. Install dependencies:

npm install

1. Build the TypeScript code:

npm run build

1. 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

freescoutgetticket

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:

Shortened. The full README is on GitHub.