loggly-mcp

Loggly MCP

Loggly /apiv2/* API に対応した読み取り専用の Model Context Protocol (MCP) サーバーです。IP インテリジェンス（RDAP、GreyNoise、AbuseIPDB）にも対応しています。書き込みエンドポイントをブロックしながら、Loggly の検索／分析／フィールド用ツール、集計を優先するトラフィック用ツール、IP コンテキスト用ツールを提供します。

---

スキルの使い方

ログを効率的に取得して（トークン使用量を抑え）、要約するには、このサーバーをスキルと組み合わせて使用してください。

---

クイックスタート

npm からインストール

LOGGLY_SUBDOMAIN=your-subdomain LOGGLY_TOKEN=your-token npx -y @andrewbabu/loggly-mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "loggly": {
      "command": "npx",
      "args": ["-y", "@andrewbabu/loggly-mcp"],
      "env": {
        "LOGGLY_SUBDOMAIN": "your-subdomain",
        "LOGGLY_TOKEN": "your-token"
      }
    }
  }
}

ソースから実行

git clone https://github.com/andrewbabu/loggly-mcp.git
cd loggly-mcp
npm install
cp .env.example .env

.env に Loggly の認証情報を設定してから、次を実行します：

npm start

Codex でリポジトリが信頼されると、.codex/config.toml を使って MCP サーバーを自動的に起動することもできます。

---

設定

サーバーは起動時に、作業ディレクトリから .env を読み込みます。

必須

• LOGGLY_SUBDOMAIN
  Loggly アカウントのサブドメインまたは Loggly の完全な URL（例：your-subdomain または https://your-subdomain.loggly.com）
• LOGGLY_TOKEN
  Loggly API トークン

任意

• LOGGLY_AUTH_MODE
bearer（デフォルト）または basic
• LOGGLY_MAX_RETRIES
  デフォルト：2
• LOGGLY_REQUEST_TIMEOUT_MS
  デフォルト：15000
• LOGGLY_LOG_LEVEL
error、warn、info（デフォルト）、または debug

---

リモート（HTTP）サーバー

チーム内の誰もがローカルにチェックアウトせずに Claude Code から利用できる stdio サーバーを用意するには、代わりに HTTP 版を実行し、社内サーバー／VM でホストします。

cp .env.example .env

Loggly の認証情報に加えて MCP_BEARER_TOKEN を .env に設定し（node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" を使って生成します）、次を実行します：

npm run start:http

これにより、MCP_HTTP_PORT（デフォルトは 8787）でステートレスな Streamable HTTP MCP サーバーが起動します：

• GET /healthz — 認証不要の稼働確認エンドポイントです。
• POST /mcp — MCP エンドポイントです。Authorization: Bearer <MCP_BEARER_TOKEN> が必要です。それ以外の /mcp へのリクエストにはすべて 401 を返します。

Loggly の認証情報はサーバー側に保持され、接続する全員が同じ Loggly アカウントへのアクセスを共有します。MCP_BEARER_TOKEN は MCP サーバー自体へのアクセスのみを制御するため、秘密情報として扱い、漏えいした場合はローテーションしてください（例：再生成して配布し直します）。

**これは社内ネットワーク／VPN 内でのみ実行してください。**パブリックインターネットに直接公開しないでください。ユーザーごとの認証ではなく、共有トークンが 1 つだけ使用されます。

Claude Code から接続する

組織の各メンバーは、リモートサーバーを一度だけ追加します：

claude mcp add --transport http loggly https://your-internal-host:8787/mcp \
  --header "Authorization: Bearer <MCP_BEARER_TOKEN>"

デプロイ先の社内ホスト名／ポートと、受け取ったトークンに置き換えてください。

Docker で実行する

docker build -t loggly-mcp .
docker run -d --name loggly-mcp -p 8787:8787 --env-file .env loggly-mcp

---

複数のアカウント／ドメイン

このサーバーでは複数の Loggly アカウント（異なるサブドメイン、異なるトークン）の認証情報を同時に保持し、ツール呼び出しごとに対象を指定できます。

LOGGLY_ACCOUNTS に、アカウント名と認証情報を対応付けた JSON オブジェクトを設定します：

LOGGLY_ACCOUNTS={"acme":{"subdomain":"acme","token":"acme_token","authMode":"bearer"},"beta":{"subdomain":"beta","token":"beta_token"}}

LOGGLY_ACCOUNTS を設定すると、LOGGLY_SUBDOMAIN／LOGGLY_TOKEN／LOGGLY_AUTH_MODE は置き換えられます。すべてのツールで任意の account 引数（例：account: "acme"）を指定して、その呼び出しで使用するアカウントの認証情報を選択できます。

• account を省略すると、LOGGLY_DEFAULT_ACCOUNT が設定されていればその値を使用し、そうでなければ "default" を使用します。それもない場合、設定済みのアカウントが 1 つだけなら、そのアカウントを使用します。
• 不明な account 値を指定すると、設定済みのアカウント名を列挙したエラーが返されます。
• iterate_events_next では、account が省略されていても、next_url のホストに一致するアカウントがちょうど 1 つあれば、そのアカウントを推定できます。

既存の単一アカウント構成（LOGGLY_SUBDOMAIN／LOGGLY_TOKEN のみ）は、これまでどおり変更なく動作します。1 つの "default" という名前のアカウントとして扱われます。

---

集計優先のトラフィックツール

生のイベントダンプは、調査に時間とコストがかかります。これらのツールは代わりに、概要（合計、上位 N 件の内訳、バケット化されたタイムライン、少数の代表的なサンプル）を返します。

• search_logs — 汎用版です。クエリと時間範囲を入力すると、集計結果を返します。
• traffic_by_ip / traffic_by_host / traffic_by_path — 同じ集計を、1 つの IP／ホスト名／パスに絞って行います。
• group_by_ip / group_by_path / group_by_user_agent — ファセットの件数のみを返します（field_facets の薄いラッパー）。完全な集計ではなく、内訳だけが必要な場合に使います。
• timeline — 範囲内のバケット化された件数を、/apiv2/events/count の呼び出しを繰り返してクライアント側で計算します（Loggly の volume-metrics エンドポイントは自由入力のテキストクエリを受け付けないため、任意の検索条件でタイムラインを取得する方法はこれだけです）。
• sample_events — 完全な結果セットではなく例が必要な場合に、代表的な生イベントを少数返します。

フィールド名は各 Loggly ソースがログをどのように解析するかによって異なり、アカウント間、さらには同じアカウント内のタグ間でも異なることがあります。そのため、これらのツールはフィールド名を検出優先で解決します。明示的に上書きされていない各役割（host_field／path_field／status_field／user_agent_field／ip_field 引数、または LOGGLY_FIELD_HOST／_PATH／_STATUS／_USER_AGENT／_IP 環境変数）について、/apiv2/fields/ を確認し、既知の役割パターンに候補を照合します。

• 一致が 1 つだけ → 自動的に使用され、結果の discovered_fields に表示されます。
• 複数の候補が考えられる場合（たとえば、ソースに ClientIp と CustIP の両方がある場合）→ 候補間で推測することはありません。代わりに ambiguous_fields に表示され、設定済みのデフォルト値にフォールバックします。対応する *_field 引数で正しいフィールドを明示してください。
• 一致なし → 設定済みのデフォルト値（host、path、status、user_agent、ip）にフォールバックします。

上書きを決める前にすべての候補を確認したい場合は、自分で list_fields を実行してください。

---

IP インテリジェンス

• rdap_lookup — 公開 RDAP（rdap.org）を通じて、IP の所有者とネットワーク登録情報（RIR、ネットブロック、組織、国）を取得します。API キーは不要です。
• ip_reputation — IP に関する GreyNoise（インターネット全体のスキャンノイズ）と AbuseIPDB（コミュニティからの不正利用報告）を取得します。GREYNOISE_API_KEY／ABUSEIPDB_API_KEY が必要です。どちらか一方が未設定でもエラーにはならず、そのデータソースの available: false が返ります。
• get_ip_context — 上記すべての情報に Loggly のトラフィック情報（1 時間／24 時間／30 日間の件数、初回／最終確認時刻、ホスト、上位パス）を組み合わせます。account が指定されていない場合、設定済みの すべての Loggly アカウントを確認し、複数のアカウントでその IP のアクティビティが見つかった場合は cross_domain_correlation をフラグ付けします。bot-traffic-triage プレイブックによると、このドメイン横断パターンは、標的型偵察とバックグラウンドノイズを見分けるための最も強力な単一のシグナルです。

IP インテリジェンスの出力は、複数ある情報源の 1 つとして扱ってください。IP の所有者やサードパーティのスキャナーによる報告などのアイデンティティ／評判データよりも、自身のログにおける行動の証拠を重視してください。調査手法の詳細については、bot-traffic-triage スキルを参照してください。

---

ロギング

MCP の標準入出力トラフィックを妨げないよう、ログは stderr に書き込まれます。
詳細度は LOGGLY_LOG_LEVEL で調整できます。デフォルトは info です。

---

タイムアウト、リトライ、並行処理

リクエストごとに LOGGLY_REQUEST_TIMEOUT_MS（デフォルトは 15000）のタイムアウトが適用されます。
一時的な障害（429、タイムアウトのような本文を伴う 500、503、504、またはネットワークタイムアウト）が発生した場合、LOGGLY_MAX_RETRIES の回数までリトライします。Loggly が 429 の際に Retry-After ヘッダーを送信する場合はそれに従い、それ以外の場合は指数バックオフを使用します。

集約ツール（search_logs、traffic_by_*、get_ip_context など）は、1 回の呼び出しで Promise.all を使って複数のリクエスト（ファセット＋タイムラインのバケット＋サンプル）を並行して実行します。LOGGLY_MAX_CONCURRENT_REQUESTS（デフォルトは 4）は、アカウントごとに同時実行できるリクエスト数を制限するため、こうした並行リクエストだけで Loggly 自身のレート制限に達することを防ぎます。集約ツールを 1 回呼び出しただけで 429 が引き続き発生する場合は、この値を下げてください。Loggly の制限に余裕がある場合は、値を上げてください。

---

ツールマニフェスト

ツールのメタデータは tool-manifest.json に保存され、src/server.js と照合して検証されます。

npm run verify:manifest

---

スモークテスト

LOGGLY_SMOKE_TEST=1 を設定すると、Loggly の認証情報なしでスモークテストを実行できます。

npm run smoke

---

実装済みの MCP ツール

低レベルの Loggly API ラッパー：

• connection_test
• create_search
• get_events
• search_and_get_events
• iterate_events_page
• iterate_events_next
• count_events
• volume_metrics
• stats_query
• list_fields
• field_facets
• raw_api_call

トラフィック集約を優先するツール：

• search_logs
• traffic_by_ip
• traffic_by_host
• traffic_by_path
• group_by_ip
• group_by_path
• group_by_user_agent
• timeline
• sample_events

IP インテリジェンス：

• rdap_lookup
• ip_reputation
• get_ip_context

---

例

ツール引数のペイロード例は examples/ にあります。

---

開発

npm test

npm test はマニフェストの検証とスモークテストを実行します。CI でも .github/workflows/ci.yml で同じチェックを実行します。

---

バージョン管理

• VERSION には現在のリリースバージョンが記載されています。
• CHANGELOG.md にはリリースごとの変更が記録されています。

---

セキュリティに関する注意事項

• .env ファイルをコミットしてはいけません。
• トークンと API キー（LOGGLY_TOKEN、LOGGLY_ACCOUNTS、GREYNOISE_API_KEY、 ABUSEIPDB_API_KEY、MCP_BEARER_TOKEN）は秘密情報として扱います。
• このサーバーは、Loggly の /apiv2/* エンドポイントへのアクセスを読み取り専用に制限します。IP インテリジェンスの呼び出し （RDAP／GreyNoise／AbuseIPDB）は、これらのサードパーティサービスへの読み取り専用 GET リクエストです。Loggly の認証情報がこれらのサービスに送信されることはなく、 IP インテリジェンスのキーが Loggly に送信されることもありません。