Langfuse MCPサーバー

PyPI Downloads Python 3.10–3.13 License: MIT

Langfuse可観測性のためのModel Context Protocolサーバー。トレースのクエリ、エラーのデバッグ、セッションの分析、プロンプトの管理が可能です。

なぜlangfuse-mcpなのか？

公式Langfuse MCPとの比較（2026年1月時点）:

	langfuse-mcp	公式
トレースと観測	あり	なし
セッションとユーザー	あり	なし
例外追跡	あり	なし
プロンプト管理	あり	あり
データセット管理	あり	なし
アノテーションキュー	あり	なし
スコア (v2)	あり	なし
ツール選択的読み込み	あり	なし

このプロジェクトは、トレース、観測、セッション、例外、プロンプト、データセット、アノテーションキュー、スコアといった完全な可観測性ツールキットを提供します。一方、公式MCPはプロンプト管理に焦点を当てています。

クイックスタート

uv (uvx用) が必要です。

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 --python 3.11 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 --python 3.11 langfuse-mcp

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

ツール (合計37個)

カテゴリ	ツール
トレース	`fetch_traces`, `fetch_trace`
観測	`fetch_observations`, `fetch_observation`
セッション	`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_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`
スキーマ	`get_data_schema`

データセットアイテムの更新 (Upsert)

Langfuseはデータセットアイテムに対してupsertを使用します。既存のアイテムを編集するには、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"}
)

スキル

このプロジェクトには、デバッグプレイブックを含むスキルが含まれています。

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」と尋ねてみてください。

詳細なドキュメントについては skills/langfuse/SKILL.md を参照してください。

ツール選択的読み込み

トークンのオーバーヘッドを減らすために、必要なツールグループのみを読み込みます:

langfuse-mcp --tools traces,prompts

利用可能なグループ: traces, observations, sessions, exceptions, prompts, datasets, annotation_queues, scores, schema

読み取り専用モード

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

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_annotation_queue, create_annotation_queue_item, update_annotation_queue_item, delete_annotation_queue_item, create_annotation_queue_assignment, delete_annotation_queue_assignment

その他のクライアント

Cursor

プロジェクト内に .cursor/mcp.json を作成します (グローバル設定の場合は ~/.cursor/mcp.json):

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

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

開発

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

ライセンス

MIT

langfuse-mcp