Langfuse Mcp

langfuse-mcp

Langfuse REST API をツールとして公開する MCP サーバーです。Claude（または任意の MCP クライアント）が会話中にトレース、オブザベーション、セッション、スコア、プロンプト、データセット、メトリクスを照会できます。

次のような質問をしたい場合に便利です。

• 「トレース abc123 が失敗した理由は何ですか？オブザベーションを順に説明してください。」
• 「ユーザー [email protected] の level=ERROR に該当する最新のトレースを5件一覧表示してください。」
• 「今日の生成コストをモデル別にまとめてください。」
• 「プロンプト customer-support-v2 の本番バージョンを表示してください。」

…アシスタントから離れることなく実行できます。

要件

• Node.js 20 以降（node --version）。
• API キーを持つ Langfuse プロジェクト（EU クラウドの場合はcloud.langfuse.com → Settings → API Keys、US クラウドの場合は us.cloud.langfuse.com、またはセルフホストのインスタンス）。

ツール

すべてのツールは読み取り専用で、プロジェクトキーを使用した Basic Auth により、HTTPS 経由で Langfuse Public API を呼び出します。

トレースとオブザベーション

Tool	Description
listTraces	フィルターを指定してトレースを一覧表示します。概要メタデータを返します。
getTrace	ID を指定して単一のトレースを取得します。オブザベーションツリー全体を含みます。
listObservations	フィルターを指定してスパン、生成、イベントを一覧表示します。
getObservation	ID を指定して単一のオブザベーションを取得します。

セッション

Tool	Description
listSessions	期間を指定してセッションを一覧表示します。
getSession	ID を指定してセッションを取得します。関連するトレースも含みます。

スコア

Tool	Description
listScores	フィルターを指定してスコアを一覧表示します。
getScore	ID を指定して単一のスコアを取得します。
listScoreConfigs	スコア設定（定義、範囲、カテゴリ）を一覧表示します。
getScoreConfig	ID を指定してスコア設定を取得します。

プロンプト

Tool	Description
listPrompts	プロンプト定義を一覧表示します。名前、ラベル、タグで絞り込むこともできます。
getPrompt	名前を指定してプロンプトを取得します。特定のバージョンまたはラベルを指定することもできます。

データセット

ツール	説明
listDatasets	Langfuse で設定されているデータセットを一覧表示します。
getDataset	名前を指定してデータセットを取得します。
listDatasetItems	データセット内の項目（入力、期待される出力、メタデータ）を一覧表示します。
getDatasetItem	ID を指定して単一のデータセット項目を取得します。
listDatasetRuns	データセットの評価実行を一覧表示します。
getDatasetRun	名前を指定して特定のデータセット実行を取得します。

メトリクス、モデルなど

ツール	説明
getMetrics	カスタムメトリクスのクエリを実行します（件数、レイテンシー、コスト、トークン使用量）。JSON クエリ文字列を渡します。
getDailyMetrics	日次で集計された使用量／コスト／件数のメトリクスです。
listModels	Langfuse が認識しているモデルを一覧表示します（コスト／トークンの割り当て用）。
getModel	ID を指定してモデル定義を取得します。
listProjects	現在の API キーでアクセス可能なプロジェクトを一覧表示します。
listComments	トレース、オブザベーション、セッション、またはプロンプトに付加されたコメントを一覧表示します。
getComment	ID を指定して単一のコメントを取得します。
getMedia	メディア添付ファイル（画像、音声、ファイル）のメタデータを取得します。
getHealth	Langfuse の公開ヘルスエンドポイントに ping を送信します。認証情報の検証に便利です。

インストール

npx を使ってインストールせずに実行します。

npx -y langfuse-mcp

または、グローバルにインストールします。

npm i -g langfuse-mcp
langfuse-mcp --version

設定

サーバーは次の 3 つの環境変数を読み込みます。

変数	必須	説明
LANGFUSE_PUBLIC_KEY	はい	プロジェクトの公開キー（pk-lf-…）。
LANGFUSE_SECRET_KEY	はい	プロジェクトのシークレットキー（sk-lf-…）。
LANGFUSE_BASE_URL	はい	例：https://cloud.langfuse.com（EU）、https://us.cloud.langfuse.com（US）、またはセルフホスト環境の URL。
LANGFUSE_ENV_FILE	いいえ	./.env の代わりに読み込む .env ファイルへの任意のパス。

キーはどこで取得できますか？ Langfuse の UI で、Settings → API Keys → Create new API keys を選択します。キーは単一のプロジェクトと単一のリージョンに紐づきます（EU と US は別々のアカウントです。キーを作成したリージョンに合わせて LANGFUSE_BASE_URL を設定してください）。

作業ディレクトリに .env ファイルがある場合は、自動的に読み込まれます。ひな形ファイルについては .env.example を参照してください。

Claude Desktop で使用する

claude_desktop_config.json を編集します。

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json
• Linux： ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "langfuse": {
      "command": "npx",
      "args": ["-y", "langfuse-mcp"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-…",
        "LANGFUSE_SECRET_KEY": "sk-lf-…",
        "LANGFUSE_BASE_URL": "https://cloud.langfuse.com"
      }
    }
  }
}

編集後、Claude Desktop を再起動します。チャット入力欄に MCP サーバーのアイコンが表示されます。

Claude Code で使用する

プロジェクトレベル（./.mcp.json）：

{
  "mcpServers": {
    "langfuse": {
      "command": "npx",
      "args": ["-y", "langfuse-mcp"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-…",
        "LANGFUSE_SECRET_KEY": "sk-lf-…",
        "LANGFUSE_BASE_URL": "https://cloud.langfuse.com"
      }
    }
  }
}

ユーザーレベルの設定は ~/.claude.json にあり、同じ形式を使用します。

Cursor で使用する

プロジェクトレベル：.cursor/mcp.json。ユーザーレベル：~/.cursor/mcp.json。

{
  "mcpServers": {
    "langfuse": {
      "command": "npx",
      "args": ["-y", "langfuse-mcp"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-…",
        "LANGFUSE_SECRET_KEY": "sk-lf-…",
        "LANGFUSE_BASE_URL": "https://cloud.langfuse.com"
      }
    }
  }
}

Cline（VS Code）で使用する

VS Code の設定（settings.json）で：

{
  "cline.mcpServers": {
    "langfuse": {
      "command": "npx",
      "args": ["-y", "langfuse-mcp"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-…",
        "LANGFUSE_SECRET_KEY": "sk-lf-…",
        "LANGFUSE_BASE_URL": "https://cloud.langfuse.com"
      }
    }
  }
}

Continue で使用する

~/.continue/config.json で：

{
  "mcpServers": [
    {
      "name": "langfuse",
      "command": "npx",
      "args": ["-y", "langfuse-mcp"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-…",
        "LANGFUSE_SECRET_KEY": "sk-lf-…",
        "LANGFUSE_BASE_URL": "https://cloud.langfuse.com"
      }
    }
  ]
}

Windsurf で使用する

Windsurf の MCP 設定に追加します：

{
  "mcpServers": {
    "langfuse": {
      "command": "npx",
      "args": ["-y", "langfuse-mcp"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-…",
        "LANGFUSE_SECRET_KEY": "sk-lf-…",
        "LANGFUSE_BASE_URL": "https://cloud.langfuse.com"
      }
    }
  }
}

その他の MCP クライアントで使用する

このサーバーは stdio 経由で MCP を使用します。任意の MCP クライアントからサブプロセスとして起動できます：

LANGFUSE_PUBLIC_KEY=pk-lf-… \
LANGFUSE_SECRET_KEY=sk-lf-… \
LANGFUSE_BASE_URL=https://cloud.langfuse.com \
npx -y langfuse-mcp

試してみる

設定が完了したら、アシスタントに次のように尋ねてみてください：

• "getHealth ツールを使って、langfuse-mcp が接続されていることを確認してください。"
• "level=ERROR の最新のトレースを5件表示してください。"
• "トレース abc123 のすべてのオブザベーションを表示してください。"
• "今週、ユーザー [email protected] が受け取ったスコアを教えてください。"
• "プロンプト customer-support の本番バージョンを取得してください。"
• "データセット eval-2026-q1 の実行を一覧表示し、最も高い正解率スコアを記録したものを教えてください。"

トラブルシューティング

初回の呼び出しで 401 Unauthorized が発生する

• リージョンが間違っています：Langfuse Cloud の EU と US は別々のアカウントです。キーを作成したリージョンに LANGFUSE_BASE_URL が一致していることを確認してください（EU は https://cloud.langfuse.com、US は https://us.cloud.langfuse.com）。
• .env 内のキーが引用符で囲まれている：このサーバーは前後の引用符を取り除きますが、余分なスペースがあると Basic Auth が失敗することがあります。キーを貼り直してください。
• 他のツールを実行する前に、getHealth を使って認証情報を確認してください。

npx が古いバージョンを使い続ける

npx -y langfuse-mcp@latest

npx はパッケージを積極的にキャッシュします。@latest サフィックスを付けると、確実に更新されます。

LANGFUSE_BASE_URL must be a full URL エラー

最もよくある原因は、スキームが抜けていることです。cloud.langfuse.com ではなく、https://cloud.langfuse.com を使用してください。

セルフホスト版 Langfuse

末尾のスラッシュやパスを付けずに、デプロイ環境の完全なベース URL を使用してください。例：https://langfuse.mycompany.internal。サーバーは末尾のスラッシュが1つだけの場合は正規化しますが、それ以外（/api、/public）が付いているとパスの結合に失敗します。

Claude Desktop に MCP サーバーのアイコンが表示されない

• Claude Desktop のログを確認してください：~/Library/Logs/Claude/mcp*.log（macOS）または %APPDATA%\Claude\Logs\（Windows）。正常に接続すると、サーバーは stderr に langfuse-mcp v… connected という行を書き込みます。
• Node 20 以降が PATH に含まれていることを確認してください（Claude Desktop はログインシェルの PATH を使用します）。
• Claude Desktop を完全に終了し（ウィンドウを閉じるだけではなく）、再起動してください。

起動時に ERR_REQUIRE_ESM / Unexpected token が表示される

Node のバージョンが古すぎます。このパッケージには Node ≥ 20 が必要です。node --version を実行し、必要に応じて（例：nvm を使用して）アップグレードしてください。

開発

git clone https://github.com/hugoles/langfuse-mcp.git
cd langfuse-mcp
npm install
cp .env.example .env       # macOS/Linux
copy .env.example .env     # Windows cmd
npm run dev                # tsx src/index.ts (no build step)

その他のスクリプト：

スクリプト	内容
npm run build	TypeScript を dist/ にコンパイルします。
npm start	ビルド済みサーバーを実行します。
npm run typecheck	tsc --noEmit を実行します。
npm run lint	ESLint を実行します。
npm run format / npm run format:check	Prettier で整形／チェックします。
npm test	Vitest を実行します。

コントリビュート

CONTRIBUTING.md を参照してください。バグ報告や PR を歓迎します。提出前に、ローカルで npm run typecheck && npm run lint && npm test を実行してください。

セキュリティ

脆弱性を発見した場合は、SECURITY.md の説明に従って、非公開で報告してください。公開の issue は作成しないでください。

ライセンス

MIT © Hugoles。