Langfuse MCP

Langfuse MCP Server

Version 1.4.2 - 包括的なセキュリティ機能と、安全に運用できる読み取り専用／読み書き両モードを備えた、Langfuse 分析用の安全な MCP サーバーです。

🔒 セキュリティを最優先した設計（v1.4.0 の新機能）

• デュアル動作モード - デフォルトでは安全な読み取り専用モードで、書き込み操作には明示的なオプトインが必要です
• 三層セキュリティ - 環境、ツールリスト、実行時の各レベルで検証します
• 書き込みツールのプレフィックス - すべてのデータ変更操作に明確な write_* プレフィックスを付けています
• 確認プロンプト - 破壊的な操作には確認が必要です
• 包括的な監査ログ - コンプライアンスとセキュリティのため、すべての書き込み操作を記録します

機能

• 32 種類以上の包括的なツール - 分析、データセット管理、コメントによるコラボレーションを網羅します
• 安全なモードシステム - 明示的なオプトインが必要な読み取り専用（デフォルト）モードと読み書きモードを備えています
• コストと使用状況の分析 - モデル、サービス、環境、期間ごとの詳細な内訳を確認できます
• データセット管理 - 検証用の例を含むテストデータセットの作成、整理、管理ができます
• コメントによるコラボレーション - トレース、オブザベーション、セッション、プロンプトにコメントを追加できます
• トレース分析とデバッグ - 高度なフィルタリング、検索、詳細なトレース検査に対応します
• システム管理 - ヘルスモニタリング、モデル管理、プロンプトテンプレートの操作に対応します
• リアルタイムテスト - モード検証を含む包括的なテストスイートを備えています

v1.4.0 の新機能

🔒 セキュリティとモードシステム：

• デフォルトは読み取り専用モードで、読み取り操作のみが許可されます
• データ変更には、明示的なオプトインが必要な読み書きモードを使用します
• 書き込みツールにプレフィックスを付与（write_create_dataset、write_delete_dataset_item など）
• 破壊的な操作には確認プロンプトを表示します
• すべての書き込み操作について包括的な監査ログを記録します

🛠️ 機能強化：

• 分析、データセット管理、コラボレーションを網羅する 32 種類以上のツール
• 直感的なモードフラグを備えた単一の CLI バイナリ：langfuse-mcp
• 移行期間中のレガシーツールのサポート
• モードに応じたツールのフィルタリングと説明

✅ 本番環境での使用に対応：

• 三層のセキュリティ検証
• モード検証を含む広範なテストカバレッジ
• 明確なエラーメッセージとユーザー向けガイダンス
• コンプライアンスに対応した構造化監査ログ

インストール

オプション 1：npx を使用（推奨）

読み取り専用モード（安全なデフォルト）：

# Only analytics and read operations - safe for most users
npx @therealsachin/langfuse-mcp
# OR explicitly use readonly binary
langfuse-mcp-ro

読み書きモード（明示的なオプトインが必要）：

# ⚠️ Enables write operations - can modify your Langfuse data
LANGFUSE_MCP_MODE=readwrite npx @therealsachin/langfuse-mcp
# OR use CLI flag
langfuse-mcp --readwrite

オプション 2：ローカル開発

git clone https://github.com/therealsachin/langfuse-mcp.git
cd langfuse-mcp
npm install
npm run build

# Test readonly mode
LANGFUSE_MCP_MODE=readonly node build/index.js

# Test readwrite mode
LANGFUSE_MCP_MODE=readwrite node build/index.js

設定

基本設定

各 Langfuse プロジェクトの環境変数を設定します：

LANGFUSE_PUBLIC_KEY=pk-lf-xxx
LANGFUSE_SECRET_KEY=sk-lf-xxx
LANGFUSE_BASEURL=https://us.cloud.langfuse.com

モードの設定（v1.4.1 の新機能）

CLI フラグまたは環境変数を使ってサーバーの動作モードを制御します：

CLI フラグ（npx の使用時に推奨）：

# Read-only mode (default, safe)
npx @therealsachin/langfuse-mcp

# Read-write mode (explicit opt-in)
npx @therealsachin/langfuse-mcp --readwrite

# Alternative explicit flag syntax
npx @therealsachin/langfuse-mcp --mode=readonly
npx @therealsachin/langfuse-mcp --mode=readwrite

環境変数（レガシーサポート）：

# Readonly mode (default, safe)
LANGFUSE_MCP_MODE=readonly

# Readwrite mode (explicit opt-in)
LANGFUSE_MCP_MODE=readwrite

Claude Desktop の設定

読み取り専用モード（ほとんどのユーザーに推奨）：

{
  "mcpServers": {
    "langfuse": {
      "command": "npx",
      "args": ["@therealsachin/langfuse-mcp"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-your-key",
        "LANGFUSE_SECRET_KEY": "sk-lf-your-secret",
        "LANGFUSE_BASEURL": "https://us.cloud.langfuse.com"
      }
    }
  }
}

読み書きモード（上級ユーザーのみ）：

{
  "mcpServers": {
    "langfuse": {
      "command": "npx",
      "args": ["@therealsachin/langfuse-mcp", "--readwrite"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-your-key",
        "LANGFUSE_SECRET_KEY": "sk-lf-your-secret",
        "LANGFUSE_BASEURL": "https://us.cloud.langfuse.com"
      }
    }
  }
}

🔒 セキュリティのベストプラクティス

⚠️ 重要：実際の API 認証情報をバージョン管理にコミットしないでください！

組み込みのセキュリティ機能（v1.4.2 の新機能）

この MCP サーバーには、複数層のセキュリティ保護が含まれています：

🛡️ HTTPS の強制

• 自動検証により、すべての接続で HTTPS プロトコルが使用されていることを確認します
• 認証情報や機密データの平文での送信を防止します
• 実行時チェックで HTTP URL を拒否し、明確なエラーメッセージを表示します
• Langfuse API との安全な通信を本番環境でも保証します

🔍 URL のサニタイズ

• エラーログ内の機密性の高いクエリパラメーターを自動的にマスキングします
• ログからの認証情報漏えいを防ぎ、情報開示を防止します
• シークレットを除去しながらデバッグ情報を保持するスマートフィルタリングを行います
• ログをクリーンに保ち、コンプライアンスに準拠させる監査証跡の保護を行います

🚨 コミット前のセキュリティフック

• 認証情報を自動検出し、実際の API キーを誤ってコミットするのを防ぎます
• Langfuse 固有のパターンで、pk-lf- および sk-lf- 形式のキーをスキャンします
• 一般的なシークレット検出で、よく使われる認証情報のパターンを検出します
• ビルド検証により、コミット前にコードがコンパイルできることを確認します
• Git 統合には Husky を使用し、ワークフローにシームレスに統合します

開発環境でコミット前フックを有効にするには：

npm install husky --save-dev
npx husky install
# Hooks are automatically configured - no manual setup needed!

認証情報の安全な管理

1. 環境変数を使用する：認証情報は環境変数に保存し、ソースファイルに直接記述しないでください
2. ローカルでは .env ファイルを使用する：ローカル開発用に .env ファイルを作成します（すでに .gitignore に含まれています）
3. プレースホルダー値を使用する：コミットするファイルでは、pk-lf-your-public-key のようなプレースホルダーを使用します
4. キーを定期的にローテーションする：Langfuse ダッシュボードで API キーを定期的に新しく生成します
5. キーの権限を制限する：必要最小限の権限を持つ、プロジェクト固有のキーを使用します

やってはいけないこと：

# ❌ NEVER commit real credentials like this:
LANGFUSE_PUBLIC_KEY=pk-lf-REAL-KEY-NEVER-COMMIT-THIS
LANGFUSE_SECRET_KEY=sk-lf-REAL-SECRET-NEVER-COMMIT-THIS

やるべきこと：

# ✅ Use placeholder values in committed files:
LANGFUSE_PUBLIC_KEY=pk-lf-your-actual-public-key
LANGFUSE_SECRET_KEY=sk-lf-your-actual-secret-key

# ✅ Store real credentials in .env file (never committed):
# Create a .env file in your project root with your actual credentials

本番環境へのデプロイ：

• 安全な環境変数管理（Kubernetes Secrets、Docker secrets、クラウドプロバイダーのシークレットマネージャーなど）を使用します
• Docker イメージや CI/CD ログに認証情報を含めないでください
• 最小権限の原則を適用します

利用可能なツール（合計 18 個）

コア分析ツール（6 個）

1. list_projects - 設定済みの Langfuse プロジェクトをすべて一覧表示します
2. project_overview - プロジェクトのコスト、トークン数、トレースの概要を取得します
3. usage_by_model - AI モデルごとの使用量とコストを内訳表示します
4. usage_by_service - サービスタグ／機能タグごとの使用量を分析します
5. top_expensive_traces - コストが最も高いトレースを検索します
6. get_trace_detail - 特定のトレースの詳細情報を取得します

拡張分析ツール（6 個）

7. get_projects - list_projects の別名（利用可能な Langfuse プロジェクトを一覧表示します）
8. get_metrics - 柔軟なフィルタリングで集計指標（コスト、トークン数、件数）をクエリします
9. get_traces - 包括的なフィルタリングオプションを使ってトレースを取得します
10. get_observations - 詳細情報とフィルタリング機能を備えた LLM の生成結果／スパンを取得します
11. get_cost_analysis - モデル別／ユーザー別、および日次の推移による詳細なコスト内訳を取得します
12. get_daily_metrics - 平均値を含む、日次の使用量の推移とパターンを取得します

システムおよび管理ツール（6 個）

13. get_observation_detail - 特定のオブザベーション／生成結果の詳細情報を取得します
14. get_health_status - Langfuse システムの健全性とステータスを監視します
15. list_models - プロジェクトで利用可能な AI モデルをすべて一覧表示します
16. get_model_detail - 特定の AI モデルの詳細情報を取得します
17. list_prompts - フィルタリングとページネーションを使って、すべてのプロンプトテンプレートを一覧表示します
18. get_prompt_detail - 特定のプロンプトテンプレートの詳細情報を取得します

Claude Desktop での使用方法

claude_desktop_config.json に追加します：

オプション 1：npx を使用（推奨）

{
  "mcpServers": {
    "langfuse-analytics": {
      "command": "npx",
      "args": ["@therealsachin/langfuse-mcp"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-xxx",
        "LANGFUSE_SECRET_KEY": "sk-lf-xxx",
        "LANGFUSE_BASEURL": "https://us.cloud.langfuse.com"
      }
    }
  }
}

オプション 2：ローカルインストール

{
  "mcpServers": {
    "langfuse-analytics": {
      "command": "node",
      "args": ["/path/to/langfuse-mcp/build/index.js"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-xxx",
        "LANGFUSE_SECRET_KEY": "sk-lf-xxx",
        "LANGFUSE_BASEURL": "https://us.cloud.langfuse.com"
      }
    }
  }
}

クエリの例

Claude Desktop と統合すると、次のような質問をできます：

分析クエリ

• 「過去 7 日間のコスト概要を表示してください」
• 「今月、最もコストが高い AI モデルはどれですか？」
• 「昨日のコストが高いトレースを上位 10 件検索してください」
• 「本番環境のサービス別に使用量を内訳表示してください」
• 「トレース xyz-123 の詳細を表示してください」

システム管理クエリ

• 「Langfuse システムの健全性を確認してください」
• 「プロジェクトで利用可能な AI モデルをすべて一覧表示してください」
• 「GPT-4 モデルの詳細を表示してください」
• 「利用可能なプロンプトテンプレートを教えてください」
• 「'customer-support' プロンプトの詳細を取得してください」

高度な分析

• 「オブザベーション abc-123 の詳細情報を表示してください」
• 「過去 1 か月の日次コストの推移を教えてください」
• 「コストが $0.10 を超えるトレースをすべて検索してください」
• 「最も高いコストを発生させているユーザーは誰ですか？」

開発

# Watch mode for development
npm run watch

# Test with MCP Inspector
npm run inspector

# Test endpoints (requires .env file)
npm run test

実際のLangfuseデータを使用したテスト

実際のLangfuseデータを使って包括的にテストするには、プロジェクトのルートに.envファイルを作成します。

# .env file (never commit this - it's in .gitignore)
LANGFUSE_PUBLIC_KEY=pk-lf-your-actual-public-key
LANGFUSE_SECRET_KEY=sk-lf-your-actual-secret-key
LANGFUSE_BASEURL=https://us.cloud.langfuse.com

テストスイート（npm run test）は、dotenvを使ってこれらの認証情報を自動的に読み込み、実際のLangfuseプロジェクトに対して13件の包括的なテストを実行します。

• ✅ 実際のコスト／トークンデータを使ったプロジェクトの概要
• ✅ サーバー側の並べ替えによるトレースの取得
• ✅ コストの高いトレースの分析
• ✅ 日次メトリクスの集計
• ✅ コスト分析の内訳
• ✅ ヘルスステータスの監視
• ✅ モデルとプロンプトの管理
• ✅ オブザベーションの詳細取得

注：認証情報を安全に保つため、.envファイルは自動的にgitの対象外になります。

NPMへの公開

✅ パッケージ公開済み！ 以下から利用できます。

# Install and run directly with npx
npx @therealsachin/langfuse-mcp

# Or install globally
npm install -g @therealsachin/langfuse-mcp

パッケージ情報：

• 名前： @therealsachin/langfuse-mcp
• バージョン： 1.1.1
• NPM URL： https://www.npmjs.com/package/@therealsachin/langfuse-mcp

プロジェクト構成

src/
├── index.ts              # Main server entry point
├── config.ts             # Project configuration loader
├── langfuse-client.ts    # Langfuse client wrapper with 18+ API methods
├── types.ts              # TypeScript type definitions
└── tools/                # All 18 MCP tools
    # Core Analytics Tools (6)
    ├── list-projects.ts
    ├── project-overview.ts
    ├── usage-by-model.ts
    ├── usage-by-service.ts
    ├── top-expensive-traces.ts
    ├── get-trace-detail.ts
    # Extended Analytics Tools (6)
    ├── get-projects.ts          # Alias for list-projects
    ├── get-metrics.ts           # Aggregated metrics
    ├── get-traces.ts            # Trace filtering
    ├── get-observations.ts      # LLM generations
    ├── get-cost-analysis.ts     # Cost breakdowns
    ├── get-daily-metrics.ts     # Daily trends
    # System & Management Tools (6)
    ├── get-observation-detail.ts    # Observation details
    ├── get-health-status.ts         # Health monitoring
    ├── list-models.ts               # AI models listing
    ├── get-model-detail.ts          # Model details
    ├── list-prompts.ts              # Prompt templates
    └── get-prompt-detail.ts         # Prompt details

docs/                     # Comprehensive documentation
├── ARCHITECTURE.md       # System design and patterns
├── DEVELOPER_GUIDE.md    # Development workflows
├── TECHNICAL_DIAGRAMS.md # Visual system flows
├── IMPLEMENTATION_NOTES.md # API implementation details
└── DOCUMENTATION_INDEX.md # Navigation guide

test-endpoints.js         # Comprehensive test suite (13 tests)

API連携

このサーバーは、複数のLangfuse公開APIエンドポイントと連携します。

コア分析API

• /api/public/metrics - JSONクエリパラメーターを使ったGETによる分析データの集計
• /api/public/metrics/daily - 日次の使用量メトリクスとコストの内訳
• /api/public/traces - トレースの一覧表示、フィルタリング、個別のトレース取得
• /api/public/observations - オブザベーションの詳細分析とLLM生成メトリクス

システム管理API

• /api/public/observations/{id} - 個々のオブザベーションの詳細とメタデータ
• /api/public/health - システムのヘルスステータスと監視
• /api/public/models - AIモデルの一覧表示と設定
• /api/public/prompts - プロンプトテンプレートの管理とバージョン管理

APIの実装に関する注記：

• メトリクスAPI：queryパラメーターにURLエンコードしたJSONを指定し、GETメソッドを使用します
• トレースAPI：高度なフィルタリング、ページネーション、並べ替えに対応しています
• オブザベーションAPI：LLM生成とスパンの詳細データを提供します
• 日次メトリクスAPI：日次集計済み使用統計に特化したエンドポイントです
• ヘルスAPI：システムステータスの監視に使うシンプルなエンドポイントです
• モデル／プロンプトAPI：ページネーション、フィルタリング、詳細取得に対応しています

すべての認証は、Langfuse APIキーを使ったBasic Authによりサーバー側で処理されます。

ドキュメント

アーキテクチャ、開発ガイド、技術図の詳細については、包括的なドキュメントを参照してください。

• docs/ARCHITECTURE.md - システム設計、パターン、実装の詳細
• docs/DEVELOPER_GUIDE.md - 開発ワークフローと一般的なタスク
• docs/TECHNICAL_DIAGRAMS.md - システムフローとコンポーネント図
• docs/DOCUMENTATION_INDEX.md - ドキュメント全体のナビゲーションガイド

トラブルシューティング

✅ 修正済み：405 Method Not Allowedエラー

以前の問題：以前のバージョンでは、APIの使い方が正しくなかったため、「405 Method Not Allowed」エラーが発生していました。

解決策：現在のバージョンでは、Langfuse APIを正しく実装することで修正済みです。

• メトリクスAPI：正しい方法である、URLエンコードしたJSONのqueryパラメーターを指定するGETメソッドを使用するようになりました
• トレースAPI：適切なフィルタリングに対応した、実際の/api/public/tracesエンドポイントを使用します
• オブザベーションAPI：正しいパラメーターを指定して/api/public/observationsエンドポイントを使用します
• 日次メトリクス：専用の/api/public/metrics/dailyエンドポイントを使用します

✅ 修正済み：コスト値がゼロになる問題

以前の問題：実際のコストデータが存在する場合でも、コスト分析ツールがゼロの値を返していました。

解決策：API レスポンスの解析におけるフィールド名のマッピングを修正し、解決済みです。

• Metrics API のレスポンス構造：API は totalCost_sum、count_count、totalTokens_sum のような集計済みフィールド名を返します
• フィールドアクセスの更新：すべてのツールで、直接のフィールド名ではなく正しい集計済みフィールド名を使用するようになりました
• 日次メトリクスの統合：コスト分析では getDailyMetrics API を使用し、より明確な日次コスト内訳を表示するようになりました
• 影響を受けるツール：get-cost-analysis、get-metrics、usage-by-model、usage-by-service、project-overview、get-daily-metrics

✅ 修正済み：レスポンスサイズと API パラメーターの問題

以前の問題：

1. get_observations が MCP のトークン上限を超えるレスポンス（200k+ トークン）を返していました
2. get_traces が 400 Bad Request エラーを返していました

適用した解決策：

• get_observations のレスポンスサイズ制御：
  • 大きなプロンプト／レスポンスの内容を除外する includeInputOutput: false パラメーターを追加（デフォルト）
  • 内容を含める場合のサイズを制限する truncateContent: 500 パラメーターを追加
  • デフォルトの上限を 25 件から 10 件のオブザベーションに削減
  • 有効にした場合、入力／出力フィールドの内容を切り詰めるように変更
• get_traces の API パラメーター修正：
  • orderBy フィールドのパラメーター検証を追加
  • デバッグ用に、リクエストの詳細全体を含むエラーログを強化
  • 詳細なエラーレスポンスを返す適切なエラー処理を追加

✅ 修正済み：コスト分析データの集計

以前の問題：日次データは正しく機能していましたが、コスト分析では合計コストとモデル別内訳がゼロで表示されていました。

根本原因：以前の修正後も、Metrics API のフィールドマッピングが正しくありませんでした。

解決策：すべての集計に、正常に機能する Daily Metrics API のデータを使用するように切り替えました。

• 合計コストの計算：問題のある Metrics API ではなく、日次データを合計するようになりました
• モデル別内訳：日次利用データからモデル別コストを抽出して集計します
• 日次内訳：取得済みの日次データを再利用するよう最適化しました
• ユーザー別内訳：引き続き Metrics API を使用しますが、デバッグ機能を強化しました

結果：

• ✅ totalCost に正しい値（日次コストの合計）が表示されるようになりました
• ✅ byModel に実際のモデル別コスト内訳が表示されるようになりました
• ✅ byDay は引き続き正常に機能します
• 🔍 byUser にデバッグ機能を追加し、残っているフィールドマッピングの問題を特定できるようにしました

✅ 修正済み：usage_by_model でコスト／トークンがゼロになる問題

以前の問題：usage_by_model ではオブザベーション数は正しく表示される一方、すべてのコストとトークンがゼロになっていました。

根本原因：コスト計算に影響していたのと同じ Metrics API のフィールドマッピングの問題です。

解決策：コスト分析で使用しているものと同じ日次メトリクスの方法を適用しました。

• 主な方法：getDailyMetrics API を使用し、日次利用内訳からモデル別コストとトークンを集計します
• フォールバック方法：日次 API が失敗した場合は、デバッグ機能を強化した従来の Metrics API にフォールバックします
• データ集計：日次データから totalCost、totalUsage、countObservations を正しく抽出します

結果：

• ✅ モデルに 0 ではなく実際の totalCost 値が表示されるようになりました
• ✅ モデルに 0 ではなく実際の totalTokens 値が表示されるようになりました
• ✅ observationCount は引き続き正しく機能します

パフォーマンスに関する考慮事項

API の効率性：サーバーは Langfuse のネイティブエンドポイントを効率的に使用するようになりました。

• Metrics クエリは Langfuse 側で処理され、最適なパフォーマンスを実現します
• トレースとオブザベーションのフィルタリングは API レベルで行われ、データ転送量を削減します
• 日次メトリクスには、事前集計済みデータを返す専用エンドポイントを使用します

環境変数

以下の環境変数が正しく設定されていることを確認してください。

LANGFUSE_PUBLIC_KEY=pk-lf-xxx     # Your Langfuse public key
LANGFUSE_SECRET_KEY=sk-lf-xxx     # Your Langfuse secret key
LANGFUSE_BASEURL=https://us.cloud.langfuse.com  # Your Langfuse instance URL