Freshdesk MCP Server

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