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
• ⚡ Modern SDK: Built on MCP SDK 1.25+ with McpServer and registerTool() patterns

What's New in v2.0

Breaking Changes:

• Search API redesigned with explicit filter parameters instead of query-string syntax
• Migrated to modern McpServer class with structured outputs
• Removed Git/GitHub tools (use dedicated Git MCP servers for workflow automation)

New Features:

• Explicit search filters: assignee, updatedSince, createdSince, page, pageSize
• Relative time support: Use "7d", "24h", "30m" in date filters
• Exponential backoff retry logic for network errors and rate limits
• Structured content responses for better type safety
• Full Zod schema validation throughout

See CHANGELOG.md for migration guide.

Installation

Prerequisites

• Node.js 18 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"
        }
      }
    }
  }
}

That's it! The server will automatically use your current workspace directory for Git operations.

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 Lang

... View full README on GitHub