Huntress

Huntress MCP サーバー

AI アシスタントに、Huntress のサイバーセキュリティプラットフォームのデータと操作への構造化されたアクセスを提供する Model Context Protocol (MCP) サーバーです。

注記： このプロジェクトは Wyre Technology によってメンテナンスされています。

クイックスタート

Claude Desktop — ダウンロードして開くだけです。

1. 最新リリースから huntress-mcp.mcpb をダウンロードします
2. ファイルを開きます（ダブルクリックするか、Claude Desktop にドラッグします）
3. プロンプトが表示されたら Huntress の認証情報（API Key、API Secret）を入力します

ターミナルも、JSON の編集も、Node.js のインストールも不要です。

Claude Code (CLI)：

claude mcp add huntress-mcp \
  -e HUNTRESS_API_KEY=your-api-key \
  -e HUNTRESS_API_SECRET=your-api-secret \
  -- npx -y github:WYRE-AI/huntress-mcp

Docker およびソースからのインストール方法については、インストールをご覧ください。

特長

• 🔌 MCP プロトコル準拠：MCP のリソースとツールを完全にサポート
• 🛡️ 包括的なセキュリティ対応範囲：エージェント、組織、インシデント、エスカレーション、請求、シグナル、ユーザーにまたがるツール
• 🔍 決定木ナビゲーション：huntress_navigate からドメインを探索し、続いてドメイン固有のツールを動的に読み込みます
• 📝 CRUD 操作：組織、メンバーシップ、インシデントなどの作成、読み取り、更新、削除操作
• 🔒 安全な認証：Huntress API の認証情報を使用した HTTP Basic 認証
• 🌐 デュアルトランスポート：stdio（ローカル）と HTTP Streamable（リモート／Docker）の両方のトランスポートをサポート
• 📦 MCPB パッケージ：MCP Bundle によるデスクトップクライアントへのワンクリックインストール
• 🐳 Docker 対応：HTTP トランスポートとヘルスチェックを備えたコンテナ化デプロイ
• ⚡ レート制限：組み込みのレートリミッターが Huntress API の制限（60 req/min）を遵守
• 📊 構造化ログ：レベルを設定可能な包括的なログ機能

目次

• インストール
• 設定
• 使い方
• ドメイン
• Docker デプロイ
• 開発
• テスト
• 貢献
• ライセンス

インストール

オプション 1：MCPB Bundle（Claude Desktop）

最も簡単な方法です — ターミナルも、JSON の編集も、Node.js のインストールも不要です。

1. 最新リリースから huntress-mcp.mcpb をダウンロードします
2. ファイルを開きます（ダブルクリックするか、Claude Desktop にドラッグします）
3. プロンプトが表示されたら Huntress の認証情報（API Key、API Secret）を入力します

Claude Code (CLI) の場合は、次のコマンドを 1 つ実行します。

claude mcp add huntress-mcp \
  -e HUNTRESS_API_KEY=your-api-key \
  -e HUNTRESS_API_SECRET=your-api-secret \
  -- npx -y github:WYRE-AI/huntress-mcp

オプション 2：Docker

イメージはコンテナ内の 0.0.0.0 でリッスンし、デフォルトで AUTH_MODE=gateway に設定されています。ポートをループバックインターフェースで公開し、サービス間通信のシークレットを渡してください。ゲートウェイモードでは、Huntress の認証情報はリクエストごとにヘッダーで渡され、環境変数からは読み込まれません。

docker run -d \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -p 127.0.0.1:8080:8080 \
  ghcr.io/wyre-ai/huntress-mcp:latest

CONDUIT_S2S_SECRET が設定されていない場合、Compose は起動を拒否します。

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

オプション 3：ソースからインストール

git clone https://github.com/WYRE-AI/huntress-mcp.git
cd huntress-mcp
npm ci
npm run build

設定

.env.example をコピーし、以下の変数を設定してください。

変数	必須	説明
HUNTRESS_API_KEY	stdio および AUTH_MODE=env の場合	Huntress API の公開キー
HUNTRESS_API_SECRET	stdio および AUTH_MODE=env の場合	Huntress API のシークレット
MCP_TRANSPORT	いいえ	stdio（デフォルト）または http
AUTH_MODE	いいえ	gateway（Docker イメージおよび Compose のデフォルト）または env。ゲートウェイモードでは、各 /mcp リクエストに X-Huntress-Api-Key と X-Huntress-Api-Secret が必要で、HUNTRESS_* へのフォールバックは行いません。env は、S2S 認証が成功した後にのみこれらの変数を使用します。
CONDUIT_S2S_SECRET	HTTP では必須	サービス間シークレット。この値が空、または既知のプレースホルダー（changeme、secret、replace-me、your-s2s-secret、その他のサンプル値）の場合、HTTP サーバーはエラーをログに記録してゼロ以外の終了コードで終了します。設定されていない場合、Compose は起動しません。実際の値をコミットしないでください。openssl rand -hex 32 で生成してください。
MCP_ALLOW_INSECURE_DEV	いいえ	CONDUIT_S2S_SECRET なしで HTTP を起動する場合に限り、ローカル開発用として値を厳密に 1 に設定します。プロセスは警告をログに記録し、X-Gateway-S2S を検証せず、127.0.0.1 のみで待ち受けます。ループバック以外の MCP_HTTP_HOST（0.0.0.0 を含む）は無視され、上書きについてログに記録されます。既知のプレースホルダーシークレットは引き続き拒否されます。
MCP_HTTP_HOST	いいえ	CONDUIT_S2S_SECRET が設定されている場合のバインドアドレスです。未設定の場合は 127.0.0.1 がデフォルトです。コンテナーイメージでは 0.0.0.0 が設定されます。
MCP_HTTP_PORT	いいえ	HTTP ポートです。デフォルトは 8080 です。
LOG_LEVEL	いいえ	ログレベル（debug、info、warn、error）です。デフォルトは info です。

/health と /healthz は認証なしで利用でき、認証情報を読み取りません。stdio トランスポートでは CONDUIT_S2S_SECRET を使用しません。

HTTP 認証

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

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

v1 は、CONDUIT_S2S_SECRET をキーとして、正確なメッセージ t=<unix seconds> に対して計算した HMAC-SHA256 を 16 進数でエンコードした値です。タイムスタンプはサーバーの時刻から 300 秒以内でなければなりません。ヘッダーがない場合、または無効な場合は 401 を返します。シークレットがログに書き込まれることはありません。

import { createHmac } from 'node:crypto';

const t = Math.floor(Date.now() / 1000);
const v1 = createHmac('sha256', process.env.CONDUIT_S2S_SECRET).update(`t=${t}`).digest('hex');
const xGatewayS2s = `t=${t},v1=${v1}`;

AUTH_MODE=gateway では、/mcp に X-Huntress-Api-Key と X-Huntress-Api-Secret も必要です。そのリクエストの認証情報は、これらのヘッダーのみを使用します。いずれかのヘッダーが欠けている場合、リクエストは 401 を返し、HUNTRESS_API_KEY / HUNTRESS_API_SECRET へのフォールバックは行いません。

await fetch('http://127.0.0.1:8080/mcp', {
  method: 'POST',
  headers: {
    'content-type': 'application/json',
    accept: 'application/json, text/event-stream',
    'x-gateway-s2s': xGatewayS2s,
    'x-huntress-api-key': apiKey,
    'x-huntress-api-secret': apiSecret,
  },
  body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list' }),
});

ドメイン

サーバーは決定木ナビゲーションを使用します。huntress_navigate から開始してドメインを選択してください。

ドメイン	ツール
accounts	アカウント情報の取得、現在のアクターの取得
agents	エージェントの一覧表示、ID によるエージェントの取得
organizations	組織の一覧表示、取得、作成、更新、削除
incidents	インシデントレポート（一覧表示／取得／解決）、修復（一覧表示／取得／承認／却下）、エスカレーション（一覧表示／取得／解決）
billing	請求レポート、サマリーレポート
signals	セキュリティシグナルの一覧表示／取得
users	メンバーシップの CRUD（一覧表示／取得／作成／更新／削除）

Docker でのデプロイ

完全な設定については、docker-compose.yml を参照してください。リポジトリに含まれる Compose サービスはゲートウェイモードです。HUNTRESS_API_KEY や HUNTRESS_API_SECRET は設定されず、env_file も使用しないため、プロジェクトの .env からコンテナーに静的なベンダー認証情報を渡すことはできません。Compose は引き続きそのファイルから CONDUIT_S2S_SECRET を補間し、未設定の場合は起動しません。ポートは 127.0.0.1 で公開されます。

cp .env.example .env
# Set CONDUIT_S2S_SECRET. Leave it empty in the example; never commit a real value.
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up -d

シングルテナント HTTP（AUTH_MODE=env）でも S2S シークレットが必要で、その後 HUNTRESS_API_KEY と HUNTRESS_API_SECRET を使用します。これはゲートウェイ Compose サービスとは別です。

docker run -d \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e HUNTRESS_API_KEY=your-key \
  -e HUNTRESS_API_SECRET=your-secret \
  -p 127.0.0.1:8080:8080 \
  ghcr.io/wyre-ai/huntress-mcp:latest

シークレットなしのローカル HTTP は開発専用です。127.0.0.1 のみでバインドし、警告をログに記録します。

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm run start:http

開発

npm ci
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