Freshdesk MCP Server

A Model Context Protocol (MCP) server that exposes Freshdesk helpdesk operations as callable tools. It provides full ticket lifecycle management, two-phase draft/send for replies and notes, contact lookup, and agent/group discovery — all through a standard MCP interface compatible with any MCP client.

Features

14 tools covering tickets, replies, notes, contacts, groups, and agents
Two-phase draft/send pattern for replies and notes — review before posting
Custom fields support on ticket create and update
Predefined filters and full query-syntax search for tickets
Client-agnostic: works with any MCP-compatible host

Prerequisites

Node.js 18 or later
A Freshdesk account with API access

Getting Your API Key

Log in to your Freshdesk account
Click your avatar in the top-right corner and select Profile Settings
Your API key is displayed in the right sidebar under Your API Key

Installation

git clone https://github.com/ArcaneSK/freshdesk-mcp-server.git
cd freshdesk-mcp-server
npm install
npm run build

Environment Setup

Copy the example environment file and fill in your credentials:

cp .env.example .env

Edit .env with your values:

FRESHDESK_API_KEY=your_api_key_here
FRESHDESK_DOMAIN=your_subdomain

Variable	Description	Example
`FRESHDESK_API_KEY`	Your Freshdesk API key (see Getting Your API Key)	`abcdef123456`
`FRESHDESK_DOMAIN`	Your Freshdesk subdomain — if your URL is `https://acme.freshdesk.com`, use `acme`	`acme`

Claude Desktop Configuration

Add the following to your Claude Desktop claude_desktop_config.json, replacing the path with your actual install location:

{
  "mcpServers": {
    "freshdesk": {
      "command": "node",
      "args": ["/path/to/freshdesk-mcp-server/dist/index.js"],
      "env": {
        "FRESHDESK_API_KEY": "your_api_key",
        "FRESHDESK_DOMAIN": "your_subdomain"
      }
    }
  }
}

Set FRESHDESK_DOMAIN to your Freshdesk subdomain only — for example, if your helpdesk URL is https://acme.freshdesk.com, use acme.

Tools Reference

Tool	Description	Key Inputs
`list_tickets`	List tickets using predefined filters	`filter`, `email`, `requester_id`, `page`
`search_tickets`	Search tickets using Freshdesk query syntax	`query` (max 512 chars)
`get_ticket`	Retrieve a single ticket with all fields	`ticket_id`, `include` (conversations, requester, stats)
`create_ticket`	Create a new ticket	`subject`, `description`, `email` or `requester_id`
`update_ticket`	Update ticket fields	`ticket_id`, `status`, `priority`, `responder_id`, `custom_fields`
`delete_ticket`	Move a ticket to trash	`ticket_id`
`draft_reply`	Stage a reply for review (does not send)	`ticket_id`, `body`, `cc_emails`
`send_reply`	Send a previously drafted reply	`draft_id`
`draft_note`	Stage a note for review (does not post)	`ticket_id`, `body`, `private`
`send_note`	Post a previously drafted note	`draft_id`
`list_contacts`	List contacts by email or search term	`email`, `search_term`, `page`
`get_contact`	Get full contact details by ID	`contact_id`
`list_groups`	List all agent groups	`page`, `per_page`
`list_agents`	List agents, optionally filtered by group	`group_id`, `page`

Two-Phase Draft/Send

Replies and notes use a two-step confirmation pattern to prevent accidental sends:

Call draft_reply or draft_note with the content. The tool returns a draft_id and a preview of the content — nothing is sent to Freshdesk.
Review the draft, then call send_reply or send_note with the draft_id to post it.

Drafts are held in memory with a 10-minute expiration window. Each draft can only be sent once. If a draft expires, create a new one.

Development

# Clone and install
git clone https://github.com/ArcaneSK/freshdesk-mcp-server.git
cd freshdesk-mcp-server
npm install

# Build
npm run build

# Run tests
npm test

# Watch mode (TypeScript)
npm run dev

License

MIT