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

1. Log in to your Freshdesk account
2. Click your avatar in the top-right corner and select Profile Settings
3. 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:

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