Freshdesk

io.github.WYRE-AIPublished by GitHub account WYRE-AIv1.0.12Updated Oct 24, 2026

MCP server for Freshdesk — tickets, contacts, companies, agents, groups, and knowledge base.

VerifiedSTDIODesktop onlyKnowledge & MemoryBusiness & Commerce

Overview

AI-generated overview

Local MCP server for Freshdesk that lets an AI assistant search, read and manage support tickets, contacts, companies, agents, groups and knowledge base content

What you can do
Tickets: search, list, get, create, update, reply, add notes, and manage conversations, including deletion of tickets and conversations with confirmation. Contacts: search, list, get, create, update, autocomplete, restore, send invites, and merge or delete with confirmation. Companies, agents and groups: search, list, get, create, update and delete, plus a check of the current agent. Knowledge base: list, get, create, update and delete solution categories, folders and articles. SLA and business hours: list and manage SLA policies, list business hours, and browse canned response folders and responses. Navigation: a decision-tree tool reveals one domain's tools at a time, with a back tool and,
When to use it
Use it when an assistant should work inside a Freshdesk helpdesk: triaging and replying to tickets, looking up customer and company records, maintaining agents and groups, or editing knowledge base articles. It suits local CLI use with your own Freshdesk account credentials.
Requirements
Runs as a local process over stdio, typically started with npx from the GitHub repository. Needs a Freshdesk account subdomain in FRESHDESK_DOMAIN and an API key in FRESHDESK_API_KEY, found under Profile Settings in the Freshdesk portal. Optional settings include AUTH_MODE, MCP_TRANSPORT and LOG_LEVEL. HTTP or Docker hosting additionally requires CONDUIT_S2S_SECRET and, in gateway mode, per-request credential headers.
Before you install
The API key in FRESHDESK_API_KEY grants access to your helpdesk data and should be kept secret. Many tools write or delete: tickets, contacts, companies, agents, groups and knowledge base articles can be created, updated or permanently deleted, and contacts can be merged or made agents. Destructive and high-impact actions are flagged and require confirmation, but review before approving. In gateway mode, credentials arrive in request headers and are not read from the environment.

Installation

In SourceWeft

  1. Open Freshdesk in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

Freshdesk MCP Server

[Build Status] [License] [Node.js]

A Model Context Protocol (MCP) server that provides AI assistants with structured access to the Freshdesk customer support platform — tickets, contacts, companies, agents, groups, the knowledge base, and SLA/business-hours configuration.

Note: This project is maintained by Wyre Technology. It wraps the published @wyre-technology/node-freshdesk SDK.

Quick Start

The primary deployment is through the WYRE MCP Gateway, which hosts the containerized server and injects per-request credentials. To run it yourself:

Claude Code (CLI):

bash
claude mcp add freshdesk-mcp \  -e FRESHDESK_DOMAIN=your-subdomain \  -e FRESHDESK_API_KEY=your-api-key \  -- npx -y github:WYRE-AI/freshdesk-mcp

FRESHDESK_DOMAIN is the part before .freshdesk.com (for https://acme.freshdesk.com it is acme). Find your FRESHDESK_API_KEY in the Freshdesk portal under Profile Settings.

Features

  • 🔌 MCP Protocol Compliance: Tools, prompts, and elicitation support
  • 🎫 Full Helpdesk Coverage: Tickets, contacts, companies, agents, groups, solutions, SLA policies, business hours, and canned responses
  • 🌳 Decision-Tree Navigation: Start at freshdesk_navigate, enter a domain to reveal its tools, and freshdesk_back to return — keeping the tool list small and focused
  • ⚠️ Destructive-Action Guardrails: Irreversible and high-impact tools are clearly flagged and confirmed via elicitation before they run
  • 🔒 Secure Authentication: HTTP Basic Auth with your Freshdesk API key (domain + key)
  • 🌐 Dual Transport: stdio (local) and Streamable HTTP (remote/Docker/gateway)
  • 🐳 Docker Ready: Containerized deployment with HTTP transport and health checks

Connecting via the Gateway

When AUTH_MODE=gateway, every /mcp request must include credentials injected by the WYRE MCP Gateway. A request missing either header returns 401 and does not fall back to FRESHDESK_DOMAIN or FRESHDESK_API_KEY in the process environment.

HeaderMaps toDescription
x-freshdesk-domainFRESHDESK_DOMAINFreshdesk account subdomain
x-freshdesk-api-keyFRESHDESK_API_KEYFreshdesk API key

Each request is stateless: the gateway provides the credentials, and the server rebuilds its Freshdesk client for that request only. When CONDUIT_S2S_SECRET is set, the request must also include a valid X-Gateway-S2S header.

Configuration

Copy .env.example and set the variables below. The stdio transport reads FRESHDESK_DOMAIN and FRESHDESK_API_KEY and does not use CONDUIT_S2S_SECRET.

VariableDescriptionDefault
FRESHDESK_DOMAINAccount subdomain (before .freshdesk.com). Required for stdio and for HTTP when AUTH_MODE=env. Gateway mode does not read it.—
FRESHDESK_API_KEYFreshdesk API key. Required for stdio and for HTTP when AUTH_MODE=env. Gateway mode does not read it.—
MCP_TRANSPORTTransport mode (stdio or http)stdio
AUTH_MODEenv (process environment) or gateway (per-request x-freshdesk-domain and x-freshdesk-api-key, no env fallback). The container image and Compose default to gateway.env
CONDUIT_S2S_SECRETRequired for HTTP. HMAC secret checked against X-Gateway-S2S on every /mcp request. The process logs an error and exits non-zero when this is empty or a known placeholder (changeme, placeholder, secret, your-s2s-secret, and similar public example values). Compose will not start when it is unset. Never commit a real value. Generate one with openssl rand -hex 32. The value is never logged.—
MCP_ALLOW_INSECURE_DEVSet to exactly 1 only for local development to start HTTP without CONDUIT_S2S_SECRET. The process logs a warning, does not enforce X-Gateway-S2S, and binds 127.0.0.1 only. A wider MCP_HTTP_HOST (including 0.0.0.0) is ignored and the override is logged. A known placeholder secret is still rejected.—
MCP_HTTP_HOSTBind address when MCP_TRANSPORT=http. Unset binds 127.0.0.1. A configured CONDUIT_S2S_SECRET honors this value (the container image sets 0.0.0.0). With no secret, the insecure-dev bypass forces 127.0.0.1.127.0.0.1
MCP_HTTP_PORTHTTP server port8080
LOG_LEVELLog level (debug, info, warn, error)info

/health stays unauthenticated and does not read credentials.

HTTP authentication

With MCP_TRANSPORT=http and CONDUIT_S2S_SECRET set, every /mcp request must include X-Gateway-S2S:

t=<unix seconds>,v1=<hex hmac-sha256>

v1 is the lowercase hex HMAC-SHA256 of the ASCII message t=<unix seconds>, keyed by CONDUIT_S2S_SECRET. The timestamp must be within 300 seconds of the server clock. A missing or invalid header returns 401 before any vendor credential is read. The secret is never written to logs or error bodies.

In AUTH_MODE=gateway, /mcp also requires x-freshdesk-domain and x-freshdesk-api-key. Those headers are the only credential source for the request. A missing header returns 401. The server does not fall back to FRESHDESK_DOMAIN or FRESHDESK_API_KEY in the process environment.

X-Gateway-S2S: t=1710000000,v1=<hmac-sha256 of "t=1710000000">x-freshdesk-domain: acmex-freshdesk-api-key: <api key>

Single-tenant HTTP (AUTH_MODE=env) still requires a valid X-Gateway-S2S header. Vendor credentials then come from FRESHDESK_DOMAIN and FRESHDESK_API_KEY.

Tool Overview

The server uses decision-tree navigation. At the top level you see only freshdesk_navigate, freshdesk_back, and freshdesk_status. Call freshdesk_navigate with a domain to reveal that domain's tools; call freshdesk_back to return to the top.

DomainTools
ticketssearch, list, get, create, update, reply, add_note, list_conversations, update_conversation, delete*, delete_conversation*
contactssearch, list, get, create, update, autocomplete, make_agent†, restore, send_invite, merge†, soft_delete†, hard_delete*
companiessearch, list, get, create, update, autocomplete, delete*
agentslist, get, me, create, update, delete*
groupslist, get, create, update, delete*
solutionscategories / folders / articles: list, get, create, update, delete*
sla-businessSLA policies (list, create, update), business hours (list, get), canned responses (list_folders, get_folder, list_responses)

* = Tier A (irreversible delete) — flagged ⚠ DESTRUCTIVE — IRREVERSIBLE, requires confirmation. † = Tier B (high-impact reversible) — flagged ⚠ HIGH-IMPACT, requires confirmation.

Read tools (search/list/get/autocomplete/status) carry no warning and are marked read-only.

freshdesk_status performs a live connectivity check by calling agents/me.

Docker Deployment

The image listens on 0.0.0.0 inside the container (MCP_HTTP_HOST) and defaults to AUTH_MODE=gateway. Publish the port on loopback and pass the S2S secret. In gateway mode the domain and API key arrive on each request as x-freshdesk-domain and x-freshdesk-api-key. They are not read from the environment.

bash
docker run \  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \  -p 127.0.0.1:8080:8080 \  freshdesk-mcp

Compose refuses to start when CONDUIT_S2S_SECRET is unset, sets AUTH_MODE=gateway, publishes 127.0.0.1:8080:8080, and does not set FRESHDESK_DOMAIN, FRESHDESK_API_KEY, or env_file:

bash
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up -d

Single-tenant HTTP (AUTH_MODE=env) still requires the S2S secret, then uses FRESHDESK_DOMAIN and FRESHDESK_API_KEY:

bash
docker run \  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \  -e AUTH_MODE=env \  -e FRESHDESK_DOMAIN=your-subdomain \  -e FRESHDESK_API_KEY=your-api-key \  -p 127.0.0.1:8080:8080 \  freshdesk-mcp

Local HTTP without a secret is development-only. It binds 127.0.0.1 even when MCP_HTTP_HOST is 0.0.0.0, and logs a warning. A known placeholder secret still refuses to start:

bash
MCP_ALLOW_INSECURE_DEV=1 npm run start:http

See docker-compose.yml. The build installs @wyre-technology/node-freshdesk from GitHub Packages via a BuildKit npmrc secret (never baked into a layer):

bash
printf '@wyre-ai:registry=https://npm.pkg.github.com\n@wyre-technology:registry=https://npm.pkg.github.com\n//npm.pkg.github.com/:_authToken=%s\n' "$(gh auth token)" > /tmp/.npmrcdocker build --secret id=npmrc,src=/tmp/.npmrc -t freshdesk-mcp .rm /tmp/.npmrc

Development

bash
export NODE_AUTH_TOKEN=$(gh auth token)   # to install @wyre-technology/node-freshdesknpm installnpm run build       # Build the projectnpm run dev         # Watch modenpm run test        # Run testsnpm run lint        # Type-checknpm run clean       # Remove dist/
# HTTP refuses to start until CONDUIT_S2S_SECRET is setCONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" npm run start:http
# Local HTTP only, without a service-to-service secret (always binds 127.0.0.1)MCP_ALLOW_INSECURE_DEV=1 npm run start:http

Testing

bash
npm test            # Run test suitenpm run test:watch  # Watch mode

Contributing

See CONTRIBUTING.md for guidelines.

License

Apache 2.0 — Copyright WYRE Technology

Source: README.md at commit fd1ba0d

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

2
  1. v1.0.12LatestOct 14, 2026
  2. v1.0.11Sep 16, 2026

Score

40% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.