Freshdesk

io.github.WYRE-AI由 GitHub 账号 WYRE-AI 发布v1.0.12更新于 Oct 24, 2026

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

已验证STDIO仅桌面知识与记忆商业与电商

概览

AI 生成的概览

面向 Freshdesk 的本地 MCP 服务器，让 AI 助手搜索、读取并管理工单、联系人、公司、客服人员、群组和知识库内容

可以做什么
工单：搜索、列出、获取、创建、更新、回复、添加备注并管理会话，经确认后可删除工单和会话。联系人：搜索、列出、获取、创建、更新、自动补全、恢复、发送邀请，经确认后可合并或删除。公司、客服人员和群组：搜索、列出、获取、创建、更新和删除，并可查看当前客服人员。知识库：列出、获取、创建、更新和删除解决方案分类、文件夹和文章。SLA 与工作时间：列出和管理 SLA 策略、列出工作时间，并浏览预设回复文件夹和回复。导航：决策树工具一次只展示一个领域的工具，并提供返回工具和状态检查。
适用场景
当助手需要在 Freshdesk 客服系统中工作时使用：分诊和回复工单、查询客户和公司记录、维护客服人员和群组，或编辑知识库文章。适合在本地命令行中使用自己的 Freshdesk 账户凭据运行。
运行要求
以 stdio 方式作为本地进程运行，通常通过 npx 从 GitHub 仓库启动。需要 Freshdesk 账户子域名（FRESHDESK_DOMAIN）和 API 密钥（FRESHDESK_API_KEY），密钥可在 Freshdesk 门户的 Profile Settings 中找到。可选设置包括 AUTH_MODE、MCP_TRANSPORT 和 LOG_LEVEL。若使用 HTTP 或 Docker 托管，还需 CONDUIT_S2S_SECRET，网关模式下还需每请求的凭据请求头。
安装前请注意
FRESHDESK_API_KEY 中的 API 密钥可访问你的客服数据，应妥善保密。许多工具会写入或删除：工单、联系人、公司、客服人员、群组和知识库文章都可被创建、更新或永久删除，联系人还可被合并或转为客服人员。破坏性和高影响操作会被标记并要求确认，但批准前仍应核对。网关模式下凭据来自请求头，不读取环境变量。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Freshdesk，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

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

来源：README.md，提交 fd1ba0d

工具

0
SourceWeft 尚未在沙箱中启动过该软件包，因此其工具未知。

版本历史

2
  1. v1.0.12最新Oct 14, 2026
  2. v1.0.11Sep 16, 2026

评分

已满足适用检查项的 40%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手；SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list，或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分

    请在仓库或注册中心条目中声明许可证。