Freshdesk

Freshdesk MCP サーバー

AI アシスタントに、Freshdesk カスタマーサポートプラットフォームのチケット、連絡先、会社、エージェント、グループ、ナレッジベース、SLA／営業時間の設定への構造化されたアクセスを提供する Model Context Protocol（MCP） サーバーです。

注記： このプロジェクトは Wyre Technology がメンテナンスしています。公開されている @wyre-technology/node-freshdesk SDK をラップしています。

クイックスタート

主なデプロイ方法は、コンテナ化されたサーバーをホストし、リクエストごとに認証情報を挿入する WYRE MCP Gateway 経由です。自分で実行するには：

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 は .freshdesk.com より前の部分です（https://acme.freshdesk.com の場合は acme）。Freshdesk ポータルの Profile Settings で FRESHDESK_API_KEY を確認できます。

機能

• 🔌 MCP プロトコル準拠：ツール、プロンプト、エリシテーションをサポート
• 🎫 ヘルプデスクを幅広くカバー：チケット、連絡先、会社、エージェント、グループ、ソリューション、SLA ポリシー、営業時間、定型返信
• 🌳 決定木型ナビゲーション：freshdesk_navigate から開始し、ドメインを入力してツールを表示します。freshdesk_back で戻ることができ、ツールリストを小さく、目的に沿った状態に保てます
• ⚠️ 破壊的操作のガードレール：取り消し不能な操作や影響の大きいツールは明確に示され、実行前にエリシテーションで確認されます
• 🔒 安全な認証：Freshdesk API キー（ドメイン＋キー）を使用した HTTP Basic 認証
• 🌐 2 種類のトランスポート：stdio（ローカル）および Streamable HTTP（リモート／Docker／ゲートウェイ）
• 🐳 Docker 対応：HTTP トランスポートとヘルスチェックを備えたコンテナ化デプロイ

Gateway 経由での接続

AUTH_MODE=gateway の場合、すべての /mcp リクエストには WYRE MCP Gateway が挿入する認証情報が必要です。いずれかのヘッダーがないリクエストは 401 を返し、プロセス環境の FRESHDESK_DOMAIN や FRESHDESK_API_KEY にはフォールバックしません。

ヘッダー	対応する環境変数	説明
x-freshdesk-domain	FRESHDESK_DOMAIN	Freshdesk アカウントのサブドメイン
x-freshdesk-api-key	FRESHDESK_API_KEY	Freshdesk API キー

各リクエストはステートレスです。ゲートウェイが認証情報を提供し、サーバーはそのリクエスト専用に Freshdesk クライアントを再構築します。CONDUIT_S2S_SECRET が設定されている場合、リクエストには有効な X-Gateway-S2S ヘッダーも含める必要があります。

設定

.env.example をコピーし、以下の変数を設定します。stdio トランスポートは FRESHDESK_DOMAIN と FRESHDESK_API_KEY を読み込み、CONDUIT_S2S_SECRET は使用しません。

変数	説明	デフォルト
FRESHDESK_DOMAIN	アカウントのサブドメイン（.freshdesk.com の前の部分）。stdio および AUTH_MODE=env の HTTP で必須です。ゲートウェイモードでは読み込まれません。	—
FRESHDESK_API_KEY	Freshdesk API キー。stdio および AUTH_MODE=env の HTTP で必須です。ゲートウェイモードでは読み込まれません。	—
MCP_TRANSPORT	トランスポートモード（stdio または http）	stdio
AUTH_MODE	env（プロセス環境変数）または gateway（リクエストごとの x-freshdesk-domain と x-freshdesk-api-key。環境変数へのフォールバックなし）。コンテナーイメージと Compose のデフォルトは gateway です。	env
CONDUIT_S2S_SECRET	HTTP で必須です。すべての /mcp リクエストで X-Gateway-S2S と照合する HMAC シークレットです。値が空、または既知のプレースホルダー（changeme、placeholder、secret、your-s2s-secret などの公開されているサンプル値）の場合、プロセスはエラーをログに記録し、ゼロ以外の終了コードで終了します。未設定の場合、Compose は起動しません。実際の値をコミットしないでください。openssl rand -hex 32 で生成できます。この値がログに記録されることはありません。	—
MCP_ALLOW_INSECURE_DEV	ローカル開発時に限り、1 を正確に設定すると、CONDUIT_S2S_SECRET なしで HTTP を起動できます。プロセスは警告をログに記録し、X-Gateway-S2S を強制せず、127.0.0.1 のみでバインドします。より広い範囲を指定する MCP_HTTP_HOST（0.0.0.0 を含む）は無視され、その上書きはログに記録されます。既知のプレースホルダーシークレットは引き続き拒否されます。	—
MCP_HTTP_HOST	MCP_TRANSPORT=http の場合のバインドアドレス。未設定の場合は 127.0.0.1 にバインドします。CONDUIT_S2S_SECRET が設定されている場合はこの値が適用されます（コンテナーイメージでは 0.0.0.0 が設定されています）。シークレットがない場合は、安全でない開発用のバイパスによって 127.0.0.1 が強制されます。	127.0.0.1
MCP_HTTP_PORT	HTTP サーバーのポート	8080
LOG_LEVEL	ログレベル（debug、info、warn、error）	info

/health は認証を必要とせず、認証情報も読み込みません。

HTTP 認証

MCP_TRANSPORT=http で CONDUIT_S2S_SECRET が設定されている場合、すべての /mcp リクエストに X-Gateway-S2S を含める必要があります。

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

v1 は、CONDUIT_S2S_SECRET をキーとして、ASCII メッセージ t=<unix seconds> の HMAC-SHA256 を小文字の 16 進数で表した値です。タイムスタンプはサーバーの時刻との差が 300 秒以内でなければなりません。ヘッダーがない場合、または無効な場合は、ベンダーの認証情報を読み込む前に 401 を返します。シークレットがログやエラーボディに書き込まれることはありません。

AUTH_MODE=gateway の場合、/mcp には x-freshdesk-domain と x-freshdesk-api-key も必要です。リクエストの認証情報は、これらのヘッダーのみから取得されます。ヘッダーがない場合は 401 を返します。サーバーはプロセス環境変数の FRESHDESK_DOMAIN や FRESHDESK_API_KEY にフォールバックしません。

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

シングルテナントの HTTP（AUTH_MODE=env）でも、有効な X-Gateway-S2S ヘッダーが必要です。ベンダーの認証情報は FRESHDESK_DOMAIN と FRESHDESK_API_KEY から取得されます。

ツールの概要

サーバーは決定木ナビゲーションを使用します。トップレベルで表示されるのは freshdesk_navigate、freshdesk_back、freshdesk_status のみです。freshdesk_navigate にドメインを指定して呼び出すと、そのドメインのツールが表示されます。freshdesk_back を呼び出すとトップに戻ります。

ドメイン	ツール
tickets	search、list、get、create、update、reply、add_note、list_conversations、update_conversation、delete*、delete_conversation*
contacts	search、list、get、create、update、autocomplete、make_agent†、restore、send_invite、merge†、soft_delete†、hard_delete*
companies	search、list、get、create、update、autocomplete、delete*
agents	list、get、me、create、update、delete*
groups	list、get、create、update、delete*
solutions	categories / folders / articles：list、get、create、update、delete*
sla-business	SLA ポリシー（list、create、update）、営業時間（list、get）、定型返信（list_folders、get_folder、list_responses）

* = Tier A（取り消し不能な削除）— ⚠ DESTRUCTIVE — IRREVERSIBLE と表示され、確認が必要です。 † = Tier B（影響の大きい、取り消し可能な操作）— ⚠ HIGH-IMPACT と表示され、確認が必要です。

読み取りツール（search/list/get/autocomplete/status）には警告がなく、読み取り専用としてマークされます。

freshdesk_status は agents/me を呼び出して、ライブ接続チェックを実行します。

Docker でのデプロイ

イメージはコンテナ内で 0.0.0.0（MCP_HTTP_HOST）をリッスンし、デフォルトで AUTH_MODE=gateway を使用します。ポートをループバックに公開し、S2S シークレットを渡してください。ゲートウェイモードでは、ドメインと API キーは各リクエストの x-freshdesk-domain と x-freshdesk-api-key として渡されます。これらは環境変数から読み込まれません。

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

CONDUIT_S2S_SECRET が未設定の場合、Compose は起動を拒否します。また、AUTH_MODE=gateway を設定し、127.0.0.1:8080:8080 を公開します。FRESHDESK_DOMAIN、FRESHDESK_API_KEY、env_file は設定しません。

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up -d

シングルテナント HTTP（AUTH_MODE=env）でも S2S シークレットが必要です。そのうえで FRESHDESK_DOMAIN と 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

シークレットを使用しないローカル HTTP は開発専用です。MCP_HTTP_HOST が 0.0.0.0 の場合でも 127.0.0.1 にバインドされ、警告がログに記録されます。既知のプレースホルダーシークレットを使用した場合も、起動は拒否されます。

MCP_ALLOW_INSECURE_DEV=1 npm run start:http

docker-compose.yml を参照してください。ビルドでは BuildKit の npmrc シークレットを使用して GitHub Packages から @wyre-technology/node-freshdesk をインストールします（レイヤーに焼き込まれることはありません）。

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

開発

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

テスト

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

貢献

ガイドラインについては CONTRIBUTING.md を参照してください。

ライセンス

Apache 2.0 — Copyright WYRE Technology