# langfuse-mcp — Query Langfuse Traces via MCP

> Connect Langfuse observability to Claude Code/Codex via MCP: fetch traces, prompts, and datasets (37 tools). Works with Langfuse Cloud or self-hosted.

## Install

Merge the JSON below into your `.mcp.json`:

## Quick Use

```bash
# Claude Code (project-scoped) example from README
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
```

## Intro

langfuse-mcp turns Langfuse into agent-queryable context: your assistant can pull real traces and prompts to debug, evaluate, and iterate on agent behavior with evidence.

**Best for:** Agent observability, prompt debugging, evaluation workflows, and incident postmortems

**Works with:** Langfuse Cloud or self-hosted; MCP clients (Claude Code/Codex); API keys via env

**Setup time:** 10–15 minutes

### Key facts (verified)

- README lists 37 tools across traces, observations, sessions, prompts, datasets, and more.
- Supports selective tool loading via `--tools traces,prompts` (README).
- GitHub: 87 stars · 23 forks; pushed 2026-05-06 (GitHub API verified).

## Main

A good “observability loop” with langfuse-mcp:

1) Ask your agent to reproduce a bug with tracing enabled.
2) Use MCP tools to fetch the trace and identify the failing observation span.
3) Pull the exact prompt version used (and labels), then patch the prompt and re-run.

If you want safer access in shared environments, enable read-only mode (`--read-only`) first.


### README excerpt (verbatim)

# Langfuse MCP Server

[![PyPI](https://badge.fury.io/py/langfuse-mcp.svg)](https://badge.fury.io/py/langfuse-mcp)
[![Downloads](https://static.pepy.tech/badge/langfuse-mcp)](https://pepy.tech/projects/langfuse-mcp)
[![Python 3.10–3.14](https://img.shields.io/badge/python-3.10–3.14-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[Model Context Protocol](https://modelcontextprotocol.io) server for [Langfuse](https://langfuse.com) observability. Query traces, debug errors, analyze sessions, manage prompts.

## Why langfuse-mcp?

Comparison with [official Langfuse MCP](https://github.com/langfuse/mcp-server-langfuse) (as of Jan 2026):

| | langfuse-mcp | Official |
|-|--------------|----------|
| **Traces & Observations** | Yes | No |
| **Sessions & Users** | Yes | No |
| **Exception Tracking** | Yes | No |
| **Prompt Management** | Yes | Yes |
| **Dataset Management** | Yes | No |
| **Annotation Queues** | Yes | No |
| **Scores (v2)** | Yes | No |
| **Selective Tool Loading** | Yes | No |

This project provides a **full observability toolkit** — traces, observations, sessions, exceptions, prompts, datasets, annotation queues, and scores — while the official MCP focuses on prompt management.

## Quick Start

Requires [uv](https://docs.astral.sh/uv/getting-started/installation/) (for `uvx`) and Python 3.10 or newer. CI verifies Python 3.10 through 3.14.

Get credentials from [Langfuse Cloud](https://cloud.langfuse.com) → Settings → API Keys. If self-hosted, use your instance URL for `LANGFUSE_HOST`.

```bash
# 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
```

To pin a CI-verified interpreter explicitly, add `--python 3.14` before `langfuse-mcp`.

Restart your CLI, then verify with `/mcp` (Claude Code) or `codex mcp list` (Codex).

## Tools (37 total)

| Category | Tools |
|----------|-------|
| Traces | `fetch_traces`, `fetch_trace` |
| Observations | `fetch_observations`, `fetch_observation` |
| Sessions | `fetch_sessions`, `get_session_details`, `get_user_sessions` |

### FAQ

**Q: How does it authenticate?**
A: README shows LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY and LANGFUSE_HOST via env vars.

**Q: Can I restrict what loads?**
A: Use `--tools` to load only the groups you need.

**Q: Is there a safe mode?**
A: README documents `--read-only` / `LANGFUSE_MCP_READ_ONLY=true`.

## Source & Thanks

> Source: https://github.com/avivsinai/langfuse-mcp
> License: MIT
> GitHub stars: 87 · forks: 23

---

<!-- ZH -->

## 快速使用

```bash
# README 给出的 Claude Code（项目级）示例
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
```

## 简介

langfuse-mcp 让 Langfuse 变成 Agent 可查询的上下文：助手能拉取真实 trace 与 prompt，用“证据”来调试、评估并迭代 Agent 行为。

**最适合：** Agent 可观测性、Prompt 调试、评估流程与复盘

**适配：** Langfuse Cloud 或自托管；MCP 客户端（Claude Code/Codex）；通过环境变量配置 Key

**配置时间：** 10–15 分钟

### 关键事实（已验证）

- README 列出共 37 个工具，覆盖 traces/observations/sessions/prompts/datasets 等。
- README 支持用 `--tools traces,prompts` 选择性加载工具组。
- GitHub：87 stars · 23 forks；最近更新 2026-05-06（GitHub API 验证）。

## 正文

用 langfuse-mcp 建立“可观测性闭环”的一个顺手流程：

1) 让 Agent 在开启 tracing 的情况下复现问题。
2) 用 MCP 拉取 trace，定位失败的 observation span。
3) 拉取当时使用的 prompt 版本（含 labels），修复后再跑一遍验证。

共享环境建议先启用只读模式（`--read-only`）降低误操作风险。


### README 原文节选（verbatim）

# Langfuse MCP Server

[![PyPI](https://badge.fury.io/py/langfuse-mcp.svg)](https://badge.fury.io/py/langfuse-mcp)
[![Downloads](https://static.pepy.tech/badge/langfuse-mcp)](https://pepy.tech/projects/langfuse-mcp)
[![Python 3.10–3.14](https://img.shields.io/badge/python-3.10–3.14-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[Model Context Protocol](https://modelcontextprotocol.io) server for [Langfuse](https://langfuse.com) observability. Query traces, debug errors, analyze sessions, manage prompts.

## Why langfuse-mcp?

Comparison with [official Langfuse MCP](https://github.com/langfuse/mcp-server-langfuse) (as of Jan 2026):

| | langfuse-mcp | Official |
|-|--------------|----------|
| **Traces & Observations** | Yes | No |
| **Sessions & Users** | Yes | No |
| **Exception Tracking** | Yes | No |
| **Prompt Management** | Yes | Yes |
| **Dataset Management** | Yes | No |
| **Annotation Queues** | Yes | No |
| **Scores (v2)** | Yes | No |
| **Selective Tool Loading** | Yes | No |

This project provides a **full observability toolkit** — traces, observations, sessions, exceptions, prompts, datasets, annotation queues, and scores — while the official MCP focuses on prompt management.

## Quick Start

Requires [uv](https://docs.astral.sh/uv/getting-started/installation/) (for `uvx`) and Python 3.10 or newer. CI verifies Python 3.10 through 3.14.

Get credentials from [Langfuse Cloud](https://cloud.langfuse.com) → Settings → API Keys. If self-hosted, use your instance URL for `LANGFUSE_HOST`.

```bash
# 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
```

To pin a CI-verified interpreter explicitly, add `--python 3.14` before `langfuse-mcp`.

Restart your CLI, then verify with `/mcp` (Claude Code) or `codex mcp list` (Codex).

## Tools (37 total)

| Category | Tools |
|----------|-------|
| Traces | `fetch_traces`, `fetch_trace` |
| Observations | `fetch_observations`, `fetch_observation` |
| Sessions | `fetch_sessions`, `get_session_details`, `get_user_sessions` |

### FAQ

**如何鉴权？**
答：README 通过环境变量提供 LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY 与 LANGFUSE_HOST。

**能限制加载范围吗？**
答：可以用 `--tools` 只加载需要的工具组。

**有没有安全模式？**
答：README 提供 `--read-only` / `LANGFUSE_MCP_READ_ONLY=true` 只读模式。

## 来源与感谢

> Source: https://github.com/avivsinai/langfuse-mcp
> License: MIT
> GitHub stars: 87 · forks: 23


---
Source: https://tokrepo.com/en/workflows/langfuse-mcp-query-langfuse-traces-via-mcp
Author: MCP Hub