Langfuse MCP (Model Context Protocol)

Langfuse MCP サーバー

利用状況： 先月の PyPI ダウンロード数は 12,518 件（pypistats、2026-08-19）。v0.10.1。

Langfuse 向けのローカル MCP サーバーとスキルです。Claude Code、Codex、Cursor、その他の MCP クライアントからトレース、セッション、例外をデバッグできます。

ネイティブの Langfuse MCP ではなく、これを使う理由

ローカルでのデバッグには、第一級のトレース、セッション、例外、ルート判定ツール、簡潔な出力／ファイルへのダンプ出力に加え、付属の langfuse スキルを利用できます。

より広範な API にホスト型でインストール不要のアクセスを利用する場合は、公式の Langfuse MCP をお使いください（スコアの書き込み、コメント、モデル、メディア）。

2026 年 6 月時点：

	langfuse-mcp	ネイティブ Langfuse MCP
主な用途	ローカルデバッグ：トレース、セッション、例外	ホスト型、インストール不要の API
デプロイ	Langfuse Python SDK 経由のローカル stdio または HTTP	/api/public/mcp でのネイティブなストリーミング可能 HTTP
トレース／セッション／例外ツール	第一級	オブザベーション／API 指向のアクセス
ルート判定ツール	あり	なし
トークンと出力の制御	簡潔な要約、切り詰め、ファイルへのダンプ出力モード、ツールグループによる制御	ホスト型のツール応答＋クライアント
メトリクスとデータセットの実行	あり	あり
プロンプト、データセット、キュー、スコアの読み取り	あり	あり
スコアの書き込み、コメント、モデル、メディア	なし	あり

ローカルデバッグには langfuse-mcp、ホスト型で幅広く利用するにはネイティブ MCP をお使いください。

2 分で失敗したトレースを確認

インストールには uvx langfuse-mcp と Langfuse API キーが必要です。Claude Code、Codex、Cursor、Docker 向けの手順はクイックスタートをご覧ください。

クライアントを再起動したら、次のように尋ねます。

find exceptions in the last day

これは既存のツールに対応します。

find_exceptions(age=1440, group_by="file")
find_exceptions_in_file(filepath="<file from the grouping>", age=1440)
get_exception_details(trace_id="<trace_id from the file results>")

find_exceptions は {group, count, observation_id, trace_id} を返します（上位 50 グループ）。各グループには代表的な observation／trace ID が含まれ、find_exceptions_in_file はすべてのエラーレコードも返します。続けて、必要に応じて次を実行します。

fetch_trace(trace_id="<trace_id>", include_observations=true)

例外ツールは observation の level == "ERROR" によってエラーを検出します（厳密な判定であり、status_message が空でないだけでは該当しません）。件数は個々の例外イベントではなく、エラーレベルの observation を表します。get_error_count.exception_count は、find_exceptions.metadata.observation_count が報告するエラー observation の合計（上位 50 件を超えるグループも含む）と同じです。例外の詳細は記録済みメタデータ（exception.type／exception.message／exception.stacktrace。トップレベルまたは metadata.attributes 内）から取得され、値がない場合は null になります。結果は特定の時点におけるスナップショットではありません。

プロジェクトリンク

• クイックスタート
• エージェントスキル
• ツール
• ツールの選択的な読み込み
• 読み取り専用モード
• その他のクライアント

クイックスタート

uv（uvx用）とPython 3.10以降が必要です。CIではPython 3.10から3.14までを検証しています。

Langfuse Cloud → Settings → API Keysから認証情報を取得します。セルフホストの場合は、LANGFUSE_HOSTにインスタンスのURLを指定してください。

# Claude Code (project-scoped, shared via .mcp.json)
claude mcp add \
  -e LANGFUSE_PUBLIC_KEY=pk-... \
  -e LANGFUSE_SECRET_KEY=sk-... \
  -e LANGFUSE_HOST=https://cloud.langfuse.com \
  --scope project \
  langfuse -- uvx langfuse-mcp

# Codex CLI (user-scoped, stored in ~/.codex/config.toml)
codex mcp add langfuse \
  --env LANGFUSE_PUBLIC_KEY=pk-... \
  --env LANGFUSE_SECRET_KEY=sk-... \
  --env LANGFUSE_HOST=https://cloud.langfuse.com \
  -- uvx langfuse-mcp

CIで検証済みのインタープリターを明示的に固定するには、langfuse-mcpの前に--python 3.14を追加します。

CLIを再起動し、/mcp（Claude Code）またはcodex mcp list（Codex）で確認してください。

エージェントスキル

このリポジトリには、Claude CodeとCodex向けの公式langfuseスキルが含まれています。このスキルは、トレースのデバッグ、例外のトリアージ、レイテンシー分析、プロンプト管理、データセットの作業に関する具体的な手順をエージェントに提供します。

エージェントがLangfuseを使うタイミングや、最初に呼び出すべきMCPツールを把握できるようにするには、このスキルをインストールしてください。

skills経由（推奨）：

npx skills add avivsinai/langfuse-mcp -g -y

skild経由：

npx skild install @avivsinai/langfuse -t claude -y

手動インストール：

cp -r skills/langfuse ~/.claude/skills/   # Claude Code
cp -r skills/langfuse ~/.codex/skills/    # Codex CLI

スキルをインストールしたら、次を試してください。

help me debug langfuse traces
find exceptions in the last day
why was this user's session slow?

MCP サーバーはツールを提供し、スキルはエージェント向けのワークフローを提供します。skills/langfuse/SKILL.md、skills/langfuse/references/setup.md、skills/langfuse/references/tool-reference.mdを参照してください。

ツール（全48個）

カテゴリ	ツール
トレース	fetch_traces, fetch_trace
観測	fetch_observations, fetch_observation
ルーティング	find_route_decisions, get_route_decision, summarize_route_decisions, find_low_confidence_route_decisions
セッション	fetch_sessions, get_session_details, get_user_sessions
例外	find_exceptions, find_exceptions_in_file, get_exception_details, get_error_count
プロンプト	list_prompts, get_prompt, get_prompt_unresolved, create_text_prompt, create_chat_prompt, update_prompt_labels
データセット	list_datasets, get_dataset, list_dataset_items, get_dataset_item, create_dataset, create_dataset_item, delete_dataset_item, list_dataset_runs, get_dataset_run, list_dataset_run_items, create_dataset_run_item, delete_dataset_run
アノテーションキュー	list_annotation_queues, create_annotation_queue, get_annotation_queue, list_annotation_queue_items, get_annotation_queue_item, create_annotation_queue_item, update_annotation_queue_item, delete_annotation_queue_item, create_annotation_queue_assignment, delete_annotation_queue_assignment
スコア	list_scores_v2, get_score_v2
メトリクス	query_metrics, get_metrics_schema
スキーマ	get_data_schema

Observations API v2では、トレースはルート観測から構成されます。fetch_tracesはルート観測がないトレースを除外し、fetch_traceは観測がないトレースを見つけられません。

データセット実行の読み取りでは、インストール済みのLangfuse SDKが対応している場合（Python SDK 4.13.1以降）、experiments APIを使用します。experimentsを提供しないセルフホストサーバー向けには、従来のルートをフォールバックとして引き続き使用します。delete_dataset_runは従来の削除ルートが利用できる間はそれを使用します。そのルートが削除された後は、delete_traces=Trueを渡した場合に限り、実行に含まれるトレースを削除します。トレースを削除すると、観測と関連するスコアも削除されます。create_dataset_run_itemは引き続き従来のリンクAPIを使用します。このAPIがなくなった場合は、SDKの実験ランナーまたはOTel取り込みを通じて実験データを作成してください。

データセット項目の更新（アップサート）

Langfuseはデータセット項目にアップサートを使用します。既存の項目を編集するには、item_idを指定してcreate_dataset_itemを呼び出します。IDが存在する場合は更新し、存在しない場合は新しい項目を作成します。

create_dataset_item(dataset_name="qa-test-cases", item_id="item_123", input={"question": "What is 2+2?"}, expected_output={"answer": "4"})

メトリクスクエリ

query_metrics はテレメトリ（コスト、レイテンシ、トークン数、件数、スコア値）をサーバー側で集計するため、生のトレースを取得せずに、エージェントは「推論コストはいくらだったか？」や「モデル別の p95 レイテンシは？」といった質問に回答できます。ビュー、ディメンション、メジャーの全カタログについては、get_metrics_schema を呼び出してください。

query_metrics(
    view="observations",
    metrics=[{"measure": "totalCost", "aggregation": "sum"}, {"measure": "latency", "aggregation": "p95"}],
    dimensions=["providedModelName"],
    age=1440,  # last 24h; or pass from_timestamp / to_timestamp
)

カーディナリティの高いフィールド（id、traceId、userId、sessionId）は、dimensions ではなく filters で使用する必要があります。v2 メトリクスエンドポイントは Langfuse Cloud 専用です。セルフホストインスタンスでは 404 が返される場合があります。

ツールの選択的な読み込み

必要なツールグループだけを読み込み、トークンのオーバーヘッドを削減します。

langfuse-mcp --tools traces,prompts

利用可能なグループ：traces、observations、routing、sessions、exceptions、prompts、datasets、annotation_queues、scores、metrics、schema

routing グループは特定のルーターに依存しません。metadata.schema_version: "mcp.route_decision.v1" を持つ Langfuse のスパンオブザベーションを読み取り、decision_id、router_name、provider、capability_id など、オブザベーションのメタデータに保存されているルート決定フィールドでフィルタリングします。

読み取り専用モード

より安全な読み取り専用アクセスのために、すべての書き込み操作を無効にします。

langfuse-mcp --read-only
# Or via environment variable
LANGFUSE_MCP_READ_ONLY=true langfuse-mcp

以下が無効になります：create_text_prompt、create_chat_prompt、update_prompt_labels、create_dataset、create_dataset_item、delete_dataset_item、create_dataset_run_item、delete_dataset_run、create_annotation_queue、create_annotation_queue_item、update_annotation_queue_item、delete_annotation_queue_item、create_annotation_queue_assignment、delete_annotation_queue_assignment

デフォルトの出力モード

MCP が公開するデフォルトの output_mode を設定すると、パラメーターを省略したクライアントは自動的に、指定したモードを使用します。

langfuse-mcp --default-output-mode full_json_file
# Or via environment variable
LANGFUSE_MCP_DEFAULT_OUTPUT_MODE=full_json_file langfuse-mcp

サポートされている値：compact、full_json_string、full_json_file

これにより、MCP ツールスキーマに表示されるデフォルトが更新されます。クライアントは、呼び出し時に output_mode を明示的に渡すことで、引き続き個別に上書きできます。

その他のクライアント

Cursor

プロジェクト内に .cursor/mcp.json を作成します（グローバルに設定する場合は ~/.cursor/mcp.json）。

{
  "mcpServers": {
    "langfuse": {
      "command": "uvx",
      "args": ["langfuse-mcp"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-...",
        "LANGFUSE_SECRET_KEY": "sk-...",
        "LANGFUSE_HOST": "https://cloud.langfuse.com",
        "LANGFUSE_MCP_DEFAULT_OUTPUT_MODE": "full_json_file"
      }
    }
  }
}

Docker（単一プロジェクト）

docker run --rm -i \
  -e LANGFUSE_PUBLIC_KEY=pk-... \
  -e LANGFUSE_SECRET_KEY=sk-... \
  -e LANGFUSE_HOST=https://cloud.langfuse.com \
  ghcr.io/avivsinai/langfuse-mcp:latest

プロファイルを使った複数プロジェクト（stdio）

ローカルクライアント（Claude Code、Codex、Cursor）では、各 Langfuse プロジェクトの認証情報をプロファイルファイルに保存し、プロジェクトごとに 1 つの MCP サーバーを登録します。各サーバーは --profile <name> を指定して起動します。

ファイルは $XDG_CONFIG_HOME/langfuse-mcp/profiles.toml にある TOML 形式です（XDG_CONFIG_HOME が設定されていない場合は ~/.config/langfuse-mcp/profiles.toml）。別のファイルを読み込むには、--profiles-file PATH または LANGFUSE_MCP_PROFILES_FILE を使用します。

[profiles.prod]
host = "https://cloud.langfuse.com"
public_key = "pk-lf-..."
secret_key_env = "LANGFUSE_PROD_SECRET_KEY"   # read the secret from this env var

[profiles.staging]
host = "https://langfuse.staging.example.com"
public_key = "pk-lf-..."
secret_key = "sk-lf-..."                       # or give the value directly

public_key、secret_key、host には、それぞれリテラル値か、値を保持する環境変数の名前を指定する <field>_env キーを設定します。host のデフォルト値は https://cloud.langfuse.com です。

claude mcp add langfuse-prod -- uvx langfuse-mcp --profile prod
claude mcp add langfuse-staging -- uvx langfuse-mcp --profile staging

{
  "mcpServers": {
    "langfuse-prod": {
      "command": "uvx",
      "args": ["langfuse-mcp", "--profile", "prod"]
    },
    "langfuse-staging": {
      "command": "uvx",
      "args": ["langfuse-mcp", "--profile", "staging"]
    }
  }
}

優先順位は、CLI フラグ（--public-key、--secret-key、--host）＞環境変数（LANGFUSE_PUBLIC_KEY、LANGFUSE_SECRET_KEY、LANGFUSE_HOST）＞選択したプロファイル＞デフォルト値です。環境変数でプロファイルの値が上書きされると、サーバーは警告をログに記録します。プロファイル名が不明な場合、またはプロファイルファイルが見つからない場合は、ファイル名と利用可能なプロファイルを示すエラーを出してサーバーが停止します。--profile が指定されていない場合は、LANGFUSE_MCP_PROFILE でプロファイルを選択します。

HTTP トランスポート — 複数のプロジェクトで共有するサーバー

1 つの永続的なサーバーインスタンスを実行し、Authorization ヘッダーで認証情報を渡して、各 MCP クライアントをそれぞれの Langfuse プロジェクトにルーティングします。

# Start a shared server (binds to localhost by default)
docker run -d -p 127.0.0.1:8000:8000 \
  -e LANGFUSE_HOST=https://cloud.langfuse.com \
  ghcr.io/avivsinai/langfuse-mcp:latest \
  --transport streamable-http --bind-host 0.0.0.0

セキュリティに関する注意： --bind-host 0.0.0.0 を指定すると、すべてのインターフェースでポートが公開されます。本番環境では、HTTPS を強制する TLS 終端リバースプロキシ（nginx、Caddy、Cloudflare Tunnel など）の背後にサーバーを配置してください。キーを含む Authorization ヘッダーは、通常の HTTP では平文で送信されます。起動時の認証情報が設定されている場合、プロキシで認証を強制する必要があります。そうしないと、Authorization ヘッダーを持たない未認証の呼び出し元がデフォルトのプロジェクトを使用できます。公開 HTTP 環境で共有する場合は、前段のプロキシですべてのリクエストを認証しない限り、デフォルトの LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY 認証情報を設定しないでください。

MCP クライアントに各プロジェクトを個別に登録し、認証情報を Basic 認証ヘッダー（base64(public_key:secret_key)）として渡します。

# Generate the header value for each project:
echo -n "pk-lf-YOURKEY:sk-lf-YOURSECRET" | base64
# cGstbGYtWU9VUktFWTpzay1sZi1ZT1VSU0VDUkVU

# Register in Claude Code (one entry per project):
claude mcp add langfuse-audit \
  --transport http http://localhost:8000/mcp \
  -H "Authorization: Basic cGstbGYtWU9VUktFWTpzay1sZi1ZT1VSU0VDUkVU"

claude mcp add langfuse-staging \
  --transport http http://localhost:8000/mcp \
  -H "Authorization: Basic <base64 for staging project>"

認証の仕様： ここでの Basic は、ユーザーのパスワードではなく Langfuse API キーを渡します。ヘッダーがない場合は、起動時の環境変数の認証情報（LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY）にフォールバックします。不正な形式のヘッダーはすべて拒否され、別のプロジェクトへの暗黙的なフォールバックはありません。

オプションの環境変数

変数	デフォルト	説明
LANGFUSE_MAX_AGE_DAYS	7	時間ベースのツール（fetch_traces、fetch_observations など）で、遡って取得する期間の上限を設定します。Langfuse インスタンスのデータ保持期間に合わせて設定してください。たとえば、保持期間が 30 日の場合は 30 に設定します。
LANGFUSE_MCP_PROFILE	未設定	プロファイルファイルから読み込むプロファイルです。--profile と同じです。プロファイルを使った複数のプロジェクトを参照してください。
LANGFUSE_MCP_PROFILES_FILE	$XDG_CONFIG_HOME/langfuse-mcp/profiles.toml	プロファイルファイルのパスです。--profiles-file と同じです。
LANGFUSE_MCP_TRACE_TIMEOUT_SECONDS	120	単一トレースの取得（fetch_trace）におけるリクエストごとの読み取りタイムアウト（秒）です。include_observations=True を指定した大きなトレースでタイムアウトする場合は、値を大きくしてください。正の整数を指定する必要があります。

開発

uv venv --python 3.14 .venv && source .venv/bin/activate
uv pip install -e ".[dev]"
pytest

ライセンス

MIT