Seq MCP

🚀 SEQ MCP Server

SEQ構造化ロギングサーバーからのログをLLMがクエリし、分析できるようにするMCP（Model Context Protocol）サーバーです。

✨ 主な機能

• イベント検索：強力なSEQフィルタ構文でログをクエリできます。
• イベント詳細の取得：特定のログイベントに関する完全な情報を取得できます。
• ログ分析：期間を指定してログパターンの統計分析を行えます。
• シグナルの一覧表示：SEQで構成された保存済みの検索/シグナルにアクセスできます。
• ヘルスチェック：SEQサーバーの状態を監視できます。

📦 インストール

オプション1：Dockerを使用する（推奨）

# GitHub Container Registryを使用する場合
docker pull ghcr.io/roeej/seq-mcp:latest

# またはDocker Hubを使用する場合
docker pull roeej/seq-mcp:latest

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

git clone https://github.com/RoeeJ/seq-mcp.git
cd seq-mcp
npm install
npm run build

📚 ドキュメント

環境変数

*SEQインスタンスで認証が有効になっている場合は必須です。

セットアップ手順

1. 環境ファイルのサンプルをコピーします。

cp .env.example .env

2. .envファイルを編集し、SEQサーバーの詳細を入力します。

SEQ_URL=http://your-seq-server:5341
SEQ_API_KEY=your-api-key-here

💻 使用例

Claude Desktopでの使用方法

macOS

1. Claude Desktopの設定を開きます。
2. 「Developer」→「Edit Config」に移動します。
3. SEQサーバーの設定を追加します。

{
  "mcpServers": {
    "seq": {
      "command": "node",
      "args": ["/absolute/path/to/seq-mcp/dist/index.js"],
      "env": {
        "SEQ_URL": "http://localhost:5341",
        "SEQ_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Codeでの使用方法

オプション1：.envファイルを使用する

1. プロジェクトのルートに.envファイルを作成します。

SEQ_URL=http://localhost:5341
SEQ_API_KEY=your-api-key-here

2. Claude CodeのMCP設定に追加します。

{
  "seq": {
    "command": "node",
    "args": ["/path/to/seq-mcp/dist/index.js"]
  }
}

オプション2：環境変数を直接使用する

{
  "seq": {
    "command": "node",
    "args": ["/path/to/seq-mcp/dist/index.js"],
    "env": {
      "SEQ_URL": "http://localhost:5341",
      "SEQ_API_KEY": "your-api-key-here",
      "SEQ_DEFAULT_LIMIT": "200",
      "SEQ_TIMEOUT": "60000"
    }
  }
}

オプション3：システム環境変数を使用する

シェルで環境変数を設定します。

# macOS/Linux - ~/.bashrcまたは~/.zshrcに追加
export SEQ_URL="http://localhost:5341"
export SEQ_API_KEY="your-api-key-here"

# Windows PowerShell
$env:SEQ_URL = "http://localhost:5341"
$env:SEQ_API_KEY = "your-api-key-here"

その後、シンプルな設定を使用します。

{
  "seq": {
    "command": "node",
    "args": ["/path/to/seq-mcp/dist/index.js"]
  }
}

SEQからAPIキーを取得する方法

1. ウェブブラウザでSEQインスタンスを開きます。
2. 「Settings」→「API Keys」に移動します。
3. 「Add API Key」をクリックします。
4. タイトル（例：「MCP Server」）を入力します。
5. 適切な権限を設定します（通常は「Read」で十分です）。
6. 生成されたAPIキーをコピーします。

Claudeでの使用例

設定が完了したら、自然な言語でログをクエリできます。

"Show me all error logs from the last hour"
"Find logs containing 'timeout' errors"
"Analyze the log patterns for my API service"
"What are the most common errors in the last 24 hours?"
"Get details for event ID abc123"

利用可能なツール

search_events

フィルタを使用してイベントを検索します。

- query: SEQフィルタ構文（例："Level = 'Error'" または "@Message like '%failed%'"）
- count: 結果の数（1 - 1000）
- fromDate/toDate: ISO日付文字列
- level: ログレベルでフィルタリング

get_event

イベントIDで特定のイベントの詳細情報を取得します。

analyze_logs

ログパターンを分析します。

- query: オプションのSEQフィルタ
- timeRange: 1h, 6h, 24h, 7d, または30d
- groupBy: 結果をグループ化するプロパティ名

list_signals

SEQで構成されたすべてのシグナル（保存済みの検索）を一覧表示します。

check_health

SEQサーバーのヘルスステータスを確認します。

トラブルシューティング

接続問題

1. SEQが実行中であることを確認する

curl http://localhost:5341/api/health

2. APIキーの権限を確認する：APIキーに「Read」権限があることを確認します。

3. ネットワーク/ファイアウォール：MCPサーバーがSEQインスタンスに到達できることを確認します。

4. タイムアウトエラー：大規模なクエリの場合はSEQ_TIMEOUTを増やします。

一般的なエラー

• "Unauthorized"：APIキーが正しいことを確認します。
• "Connection refused"：SEQ_URLを確認し、SEQが実行中であることを確認します。
• "Timeout"：クエリが複雑すぎる可能性があります。より具体的なフィルタを追加してみてください。

開発

# 開発モードで実行
npm run dev

# テストを実行
npm test

# コードのリント
npm run lint

# 型チェック
npm run typecheck

SEQクエリの例

• Level = 'Error' - すべてのエラーログ
• @Message like '%timeout%' - 「timeout」を含むメッセージ
• Application = 'MyApp' and Level in ['Warning', 'Error'] - MyAppの警告とエラー
• @Timestamp > Now() - 1h - 直近1時間のイベント
• StatusCode >= 400 - HTTPエラー
• Environment = 'Production' and ResponseTime > 1000 - 本番環境での遅いリクエスト
• UserId = '12345' - 特定のユーザーのすべてのログ
• @Exception is not null - 例外を含むすべてのログ

高度な設定

Dockerでの使用

SEQがDockerで実行されている場合：

{
  "seq": {
    "command": "node",
    "args": ["/path/to/seq-mcp/dist/index.js"],
    "env": {
      "SEQ_URL": "http://host.docker.internal:5341",
      "SEQ_API_KEY": "your-api-key"
    }
  }
}

リモートSEQでの使用

クラウドホストされたSEQインスタンスの場合：

{
  "seq": {
    "command": "node",
    "args": ["/path/to/seq-mcp/dist/index.js"],
    "env": {
      "SEQ_URL": "https://seq.yourcompany.com",
      "SEQ_API_KEY": "your-api-key",
      "SEQ_TIMEOUT": "60000"
    }
  }
}

Dockerの使用方法

コンテナの実行

# 基本的な使用方法
docker run --rm \
  -e SEQ_URL=http://host.docker.internal:5341 \
  -e SEQ_API_KEY=your-api-key \
  ghcr.io/roeej/seq-mcp:latest

# すべての環境変数を使用する場合
docker run --rm \
  -e SEQ_URL=http://your-seq-server:5341 \
  -e SEQ_API_KEY=your-api-key \
  -e SEQ_DEFAULT_LIMIT=200 \
  -e SEQ_TIMEOUT=60000 \
  ghcr.io/roeej/seq-mcp:latest

Claude Desktop（Docker）での使用

Claude Desktopの設定に追加します。

{
  "mcpServers": {
    "seq": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "SEQ_URL=http://host.docker.internal:5341",
        "-e", "SEQ_API_KEY=your-api-key",
        "ghcr.io/roeej/seq-mcp:latest"
      ]
    }
  }
}

Claude Code（Docker）での使用

{
  "seq": {
    "command": "docker",
    "args": [
      "run",
      "--rm",
      "-i",
      "-e", "SEQ_URL=http://your-seq-server:5341",
      "-e", "SEQ_API_KEY=your-api-key",
      "ghcr.io/roeej/seq-mcp:latest"
    ]
  }
}

Docker Composeの例

docker-compose.ymlを作成します。

version: '3.8'

services:
  seq-mcp:
    image: ghcr.io/roeej/seq-mcp:latest
    environment:
      - SEQ_URL=http://seq:5341
      - SEQ_API_KEY=${SEQ_API_KEY}
    networks:
      - seq-network

  seq:
    image: datalust/seq:latest
    ports:
      - "5341:5341"
    environment:
      - ACCEPT_EULA=Y
    networks:
      - seq-network

networks:
  seq-network:
    driver: bridge

アーキテクチャ

• MCPサーバー：ツール定義とリクエストルーティングを処理します。
• SEQクライアント：SEQとのAPI通信を管理します。
• 型安全性：Zod検証を使用した完全なTypeScriptで構築されています。
• エラーハンドリング：グレースフルデグラデーションと意味のあるエラーメッセージを提供します。

セキュリティ

• APIキーはログに記録されたり、公開されたりすることはありません。
• すべてのリクエストは実行前に検証されます。
• 長時間実行されるクエリに対するタイムアウト保護があります。
• 読み取り専用操作（ログの変更は行われません）
• HTTPとHTTPSの両方の接続をサポートしています。

CI/CDパイプライン

このプロジェクトは、継続的インテグレーションとデプロイメントにGitHub Actionsを使用しています。

• CI：コード品質を確保するために、すべてのプッシュとPRで実行されます。

  • ESLintでのリント
  • TypeScriptでの型チェック
  • Vitestでのユニットテスト
  • 複数バージョンのNode.jsでのテスト（18.x, 20.x）

• Dockerの公開：

  • メインブランチで自動的にビルドされ、GitHub Container Registryに公開されます。
  • バージョンタグでDocker Hubに公開されます。
  • マルチプラットフォームビルド（linux/amd64, linux/arm64）
  • セマンティックバージョニングタグ

リリースの作成

1. リリースにタグを付けます。

git tag v1.0.0
git push origin v1.0.0

2. GitHub Actionが自動的に以下の処理を行います。

• マルチプラットフォームのDockerイメージをビルドします。
• ghcr.io/roeej/seq-mcp:1.0.0にプッシュします。
• dockerhub/roeej/seq-mcp:1.0.0にプッシュします（シークレットの設定が必要です）。

必要なGitHubシークレット

Docker Hubへの公開（オプション）の場合：

• DOCKERHUB_USERNAME：Docker Hubのユーザー名
• DOCKERHUB_TOKEN：Docker Hubのアクセストークン

注：GitHub Container Registry（ghcr.io）への公開は、リポジトリのGITHUB_TOKENで自動的に機能し、追加の設定は必要ありません。

コントリビュートの方法

1. リポジトリをフォークします。
2. 機能ブランチを作成します（git checkout -b feature/amazing-feature）。
3. 変更をコミットします（git commit -m 'Add some amazing feature'）。
4. ブランチにプッシュします（git push origin feature/amazing-feature）。
5. プルリクエストを開きます。

📄 ライセンス

MIT