English Français العربية

Freshdesk

السجل الرسمي الذكاء الاصطناعي والوكلاء

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

الشيفرة المصدرية الموقع التوثيق

ماذا يمكنك أن تفعل مع Freshdesk؟

  • 🔌 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

التثبيت

أضف هذا إلى إعدادات MCP في عميلك (Claude Desktop: claude_desktop_config.json، وCursor: ‏.cursor/mcp.json، ويستخدم VS Code وغيره الصيغة نفسها «mcpServers»).

OCI package ghcr.io/wyre-ai/freshdesk-mcp:v1.0.12
Claude Code 
claude mcp add freshdesk -e 'FRESHDESK_DOMAIN=<FRESHDESK_DOMAIN>' -e 'FRESHDESK_API_KEY=<your freshdesk_api_key>' -e 'MCP_TRANSPORT=stdio' -e 'AUTH_MODE=env' -e 'LOG_LEVEL=info' -- docker run -i --rm ghcr.io/wyre-ai/freshdesk-mcp:v1.0.12
إعداد JSON (Claude Desktop وCursor وVS Code) 
{
    "mcpServers": {
        "freshdesk": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "ghcr.io/wyre-ai/freshdesk-mcp:v1.0.12"
            ],
            "env": {
                "FRESHDESK_DOMAIN": "<FRESHDESK_DOMAIN>",
                "FRESHDESK_API_KEY": "<your freshdesk_api_key>",
                "MCP_TRANSPORT": "stdio",
                "AUTH_MODE": "env",
                "LOG_LEVEL": "info"
            }
        }
    }
}

متغيرات البيئة

  • FRESHDESK_DOMAIN إلزامي Freshdesk account subdomain — the part before .freshdesk.com (e.g. 'acme')
  • FRESHDESK_API_KEY إلزامي سري Freshdesk API key (found under Profile Settings in the Freshdesk portal)
  • MCP_TRANSPORT Transport mode for the server. Set to 'stdio' for local CLI use; the image defaults to 'http' for gateway hosting.
  • AUTH_MODE Credential source: 'env' reads vars locally, 'gateway' expects header injection from the WYRE MCP Gateway.
  • LOG_LEVEL Log verbosity: debug, info, warn, error

التوثيق

مأخوذ من ملف README للمشروع على GitHub ويُحدَّث أسبوعيًا. تفتح الروابط على GitHub.

المحتويات
  1. Freshdesk MCP Server
  2. Quick Start
  3. Features
  4. Connecting via the Gateway
  5. Configuration
  6. Tool Overview
  7. Docker Deployment
  8. Development
  9. Testing
  10. Contributing
  11. License

Freshdesk MCP Server

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):

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: acme
x-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.

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:

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:

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:

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):

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/.npmrc
docker build --secret id=npmrc,src=/tmp/.npmrc -t freshdesk-mcp .
rm /tmp/.npmrc

Development

export NODE_AUTH_TOKEN=$(gh auth token)   # to install @wyre-technology/node-freshdesk
npm install
npm run build       # Build the project
npm run dev         # Watch mode
npm run test        # Run tests
npm run lint        # Type-check
npm run clean       # Remove dist/

# HTTP refuses to start until CONDUIT_S2S_SECRET is set
CONDUIT_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

npm test            # Run test suite
npm run test:watch  # Watch mode

Contributing

See CONTRIBUTING.md for guidelines.

License

Apache 2.0 — Copyright WYRE Technology

الأسئلة الشائعة

ما هو Freshdesk؟

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

كيف أثبّت Freshdesk؟

يعمل على جهازك. في Claude Code: claude mcp add freshdesk -e 'FRESHDESK_DOMAIN=<FRESHDESK_DOMAIN>' -e 'FRESHDESK_API_KEY=<your freshdesk_api_key>' -e 'MCP_TRANSPORT=stdio' -e 'AUTH_MODE=env' -e 'LOG_LEVEL=info' -- docker run -i --rm ghcr.io/wyre-ai/freshdesk-mcp:v1.0.12. وفي العملاء الآخرين، الصق إعداد JSON من هذه الصفحة في إعدادات MCP الخاصة بهم.

هل يحتاج Freshdesk إلى مفتاح API؟

نعم. يتطلب FRESHDESK_DOMAIN, FRESHDESK_API_KEY، وتضبطها في إعداداته.

هل Freshdesk مفتوح المصدر؟

شيفرته علنية على GitHub، لكن المستودع لا يعلن ترخيصًا قياسيًا.

من يصون Freshdesk؟

ينشره WYRE-AI. يدرجه AI.tn لكنه لا يصونه ولا يوصي به.

من سجل MCP الرسمي. الإدراج ليس توصية: راجع شيفرة الخادم وصلاحياته قبل منحه الوصول إلى بياناتك.