@mindstone/mcp-server-freshdesk

Freshdesk Support MCP server for Model Context Protocol hosts. Manage helpdesk tickets, search and filter support requests, reply to customers, add internal notes, and configure Freshdesk accounts — all through a standardised MCP interface.

Status

• Version: 0.3.1 · npm
• Auth: API key (per-account, on disk via FRESHDESK_CONFIG_PATH)
• Tools: 20 (accounts, tickets, contacts, companies, knowledge base, discovery)
• Surface: cloud-api
• Machine-readable: STATUS.json

Requirements

• Node.js 20+
• npm

One-click install

After clicking the button, your host will prompt you to fill: FRESHDESK_CONFIG_PATH.

{
  "mcpServers": {
    "Freshdesk": {
      "command": "npx",
      "args": [
        "-y",
        "@mindstone/mcp-server-freshdesk"
      ],
      "env": {
        "FRESHDESK_CONFIG_PATH": "~/.mcp/freshdesk"
      }
    }
  }
}

Quick Start

Install & build

cd <path-to-repo>/connectors/freshdesk
npm install
npm run build

npx (once published)

npx -y @mindstone/mcp-server-freshdesk

Local

node dist/index.js

Configuration

Environment variables

• FRESHDESK_CONFIG_PATH — path to the config directory that stores account credentials (defaults to ~/.mcp/freshdesk)
• MCP_HOST_BRIDGE_STATE — optional path to a host bridge state file used for credential management
• MINDSTONE_REBEL_BRIDGE_STATE — backwards-compatible alias for MCP_HOST_BRIDGE_STATE

Host configuration examples

Claude Desktop / Cursor

{
  "mcpServers": {
    "Freshdesk": {
      "command": "npx",
      "args": ["-y", "@mindstone/mcp-server-freshdesk"],
      "env": {
        "FRESHDESK_CONFIG_PATH": "~/.mcp/freshdesk"
      }
    }
  }
}

Local development (no npm publish needed)

{
  "mcpServers": {
    "Freshdesk": {
      "command": "node",
      "args": ["<path-to-repo>/connectors/freshdesk/dist/index.js"],
      "env": {
        "FRESHDESK_CONFIG_PATH": "~/.mcp/freshdesk"
      }
    }
  }
}

Tools (20)

Account management

• configure_freshdesk — Connect a Freshdesk account using subdomain and API key
• list_freshdesk_accounts — List connected Freshdesk accounts with agent emails
• remove_freshdesk_account — Disconnect a Freshdesk account

Tickets

• list_freshdesk_tickets — List tickets using predefined filters
• get_freshdesk_ticket — Get a single ticket by ID with optional conversations
• search_freshdesk_tickets — Search tickets using Freshdesk query syntax
• create_freshdesk_ticket — Create a new ticket
• update_freshdesk_ticket — Update ticket fields, status, or assignee
• reply_to_freshdesk_ticket — Add a public reply to a ticket
• add_freshdesk_note — Add a private or public note to a ticket

Discovery

• list_freshdesk_ticket_fields — List all ticket fields including custom fields
• list_freshdesk_agents — List agents (support staff); use the IDs as responder_id when assigning tickets
• list_freshdesk_groups — List groups (agent teams); use the IDs as group_id when assigning tickets

Contacts & companies

• list_freshdesk_contacts — List contacts, optionally filtered by exact email or company ID
• search_freshdesk_contacts — Search contacts using Freshdesk query syntax
• get_freshdesk_contact — Get a single contact by ID
• list_freshdesk_companies — List customer organisations
• get_freshdesk_company — Get a single company by ID

Knowledge base

• search_freshdesk_solutions — Search solution articles by keyword (paginated: 30 per page, page parameter, hasMore indicator)
• get_freshdesk_solution_article — Get a full solution article by ID

Security

• Every string returned by the Freshdesk API (names, bodies, tags, emails, phone numbers, company domains, custom-field keys/values, ticket-field metadata, …) is wrapped in <untrusted-content source="…"> envelopes so the host LLM treats it as data, not instructions. Only numeric connector metadata (IDs, statuses, priorities) is returned raw.
• Credentials are stored in accounts.json under FRESHDESK_CONFIG_PATH with 0600 permissions (config directory 0700).
• Vendor error bodies, raw Retry-After header text, and query-bearing URLs are never written to logs or surfaced in tool errors.
• Invalid status/priority values and out-of-range IDs/pagination inputs are rejected before any request is made.

Licence

FSL-1.1-MIT — Functional Source License, Version 1.1, with MIT future licence. The software converts to MIT licence on 2030-04-08.