Langfuse MCP (Model Context Protocol)

by avivsinai

99 stars

711 downloads

Not rated

GitHub Website

About

A Model Context Protocol (MCP) server for Langfuse, enabling AI agents to query Langfuse trace data for enhanced debugging and observability

Details

Author: avivsinai
GitHub stars: 99
Downloads: 711
Categories: Other, Developer Tools

- 48 tools covering traces, observations, sessions, exceptions, prompts, datasets, annotation queues, scores, metrics, and schema.
- Selective tool loading via --tools flag to reduce token overhead.
- Read‑only mode (--read-only) disables all write operations.
- Default output mode (--default-output-mode) for compact, full JSON string, or file output.
- Support for HTTP transport with per‑project credentials via Authorization header.
- Included agent skill with playbooks for trace debugging, exception triage, latency analysis, prompt management, and dataset work.

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name Langfuse MCP (Model Context Protocol)

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "langfuse mcp (model context protocol)": {
            "langfuse-mcp": {
                "command": "npx",
                "args": [
                    "skills",
                    "add",
                    "avivsinai/langfuse-mcp",
                    "-g",
                    "-y"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "langfuse mcp (model context protocol)": {
            "langfuse-mcp": {
                "command": "npx",
                "args": [
                    "skills",
                    "add",
                    "avivsinai/langfuse-mcp",
                    "-g",
                    "-y"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "langfuse mcp (model context protocol)": {
            "langfuse-mcp": {
                "command": "npx",
                "args": [
                    "skills",
                    "add",
                    "avivsinai/langfuse-mcp",
                    "-g",
                    "-y"
                ]
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "langfuse mcp (model context protocol)": {
            "langfuse-mcp": {
                "command": "npx",
                "args": [
                    "skills",
                    "add",
                    "avivsinai/langfuse-mcp",
                    "-g",
                    "-y"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "langfuse mcp (model context protocol)": {
            "langfuse-mcp": {
                "command": "npx",
                "args": [
                    "skills",
                    "add",
                    "avivsinai/langfuse-mcp",
                    "-g",
                    "-y"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "langfuse mcp (model context protocol)": {
            "langfuse-mcp": {
                "command": "npx",
                "args": [
                    "skills",
                    "add",
                    "avivsinai/langfuse-mcp",
                    "-g",
                    "-y"
                ]
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "langfuse mcp (model context protocol)": {
            "langfuse-mcp": {
                "command": "npx",
                "args": [
                    "skills",
                    "add",
                    "avivsinai/langfuse-mcp",
                    "-g",
                    "-y"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "langfuse mcp (model context protocol)": {
            "langfuse-mcp": {
                "command": "npx",
                "args": [
                    "skills",
                    "add",
                    "avivsinai/langfuse-mcp",
                    "-g",
                    "-y"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "langfuse mcp (model context protocol)": {
            "langfuse-mcp": {
                "command": "npx",
                "args": [
                    "skills",
                    "add",
                    "avivsinai/langfuse-mcp",
                    "-g",
                    "-y"
                ]
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "langfuse mcp (model context protocol)": {
            "langfuse-mcp": {
                "command": "npx",
                "args": [
                    "skills",
                    "add",
                    "avivsinai/langfuse-mcp",
                    "-g",
                    "-y"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "langfuse mcp (model context protocol)": {
            "langfuse-mcp": {
                "command": "npx",
                "args": [
                    "skills",
                    "add",
                    "avivsinai/langfuse-mcp",
                    "-g",
                    "-y"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "langfuse mcp (model context protocol)": {
            "langfuse-mcp": {
                "command": "npx",
                "args": [
                    "skills",
                    "add",
                    "avivsinai/langfuse-mcp",
                    "-g",
                    "-y"
                ]
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "langfuse mcp (model context protocol)": {
            "langfuse-mcp": {
                "command": "npx",
                "args": [
                    "skills",
                    "add",
                    "avivsinai/langfuse-mcp",
                    "-g",
                    "-y"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "langfuse mcp (model context protocol)": {
            "langfuse-mcp": {
                "command": "npx",
                "args": [
                    "skills",
                    "add",
                    "avivsinai/langfuse-mcp",
                    "-g",
                    "-y"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "langfuse mcp (model context protocol)": {
            "langfuse-mcp": {
                "command": "npx",
                "args": [
                    "skills",
                    "add",
                    "avivsinai/langfuse-mcp",
                    "-g",
                    "-y"
                ]
            }
        }
    }
}

From the repository

Install via uvx langfuse-mcp with Python 3.10+ and the uv runtime. Set environment variables LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, and LANGFUSE_HOST (defaults to Langfuse Cloud). Add the server to an MCP client (Claude Code, Codex, Cursor) using the provided configuration commands or JSON files. Start the MCP client, then invoke tools directly or use the included agent skill for ready‑made debugging playbooks.

`listTraces`

List Langfuse traces with filters. Returns summary metadata (use getTrace for the full observation tree).

`getTrace`

Fetch a single trace by id including all nested observations.

`listObservations`

List observations (spans, generations, events) with filters.

`getObservation`

Fetch a single observation by id.

`listSessions`

List sessions within a time range.

`getSession`

Fetch a session by id, including its traces.

`listScores`

List scores with filters.

`getScore`

Fetch a single score by id.

`listScoreConfigs`

List score configurations (definitions for score names, ranges, and categories).

`getScoreConfig`

Fetch a single score configuration by id.

`listPrompts`

List prompt definitions tracked in Langfuse.

`getPrompt`

Fetch a prompt by name. Optionally pin to a specific version or label (e.g. 'production').

`listDatasets`

List datasets configured in Langfuse.

`getDataset`

Fetch metadata for a dataset by its name.

`listDatasetItems`

List items in a dataset (inputs / expected outputs / metadata).

`getDatasetItem`

Fetch a single dataset item by id.

`listDatasetRuns`

List runs (evaluation rounds) for a dataset.

`getDatasetRun`

Fetch a specific dataset run by name.

`getMetrics`

Run a metrics query (counts, latency, cost, token usage). Pass a JSON query string per the Langfuse metrics API.

`getDailyMetrics`

Fetch daily aggregated usage / cost / count metrics for traces and observations.

`listModels`

List models known to Langfuse (for cost / token attribution).

`getModel`

Fetch a single model definition by id.

`listProjects`

List projects accessible to the current API key (typically a single project).

`listComments`

List comments attached to traces, observations, sessions, or prompts.

`getComment`

Fetch a single comment by id.

`getMedia`

Fetch metadata for a media attachment (image, audio, file) by id.

`getHealth`

Pings the Langfuse public health endpoint. Useful to validate credentials and connectivity.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "langfuse mcp (model context protocol)": {
            "langfuse-mcp": {
                "command": "npx",
                "args": [
                    "skills",
                    "add",
                    "avivsinai/langfuse-mcp",
                    "-g",
                    "-y"
                ]
            }
        }
    }
}

McpServers

{
    "langfuse-mcp": {
        "command": "npx",
        "args": [
            "skills",
            "add",
            "avivsinai/langfuse-mcp",
            "-g",
            "-y"
        ]
    }
}

Langfuse MCP Server

Agent-facing Model Context Protocol server and skill for Langfuse observability.

Use langfuse-mcp from Claude Code, Codex, Cursor, or any MCP client to query traces, inspect generations, debug exceptions, analyze sessions, manage prompts, browse datasets, and understand what your AI agents did in production.

What You Can Do

- Debug failing agent runs from Langfuse traces and observations.
- Find exceptions, slow generations, high-latency spans, and affected users.
- Inspect sessions and user journeys without leaving your agent workflow.
- Manage prompt versions, labels, datasets, annotation queues, and scores.
- Install the included langfuse agent skill for ready-made debugging playbooks.

Project Links

- Quick Start
- Agent Skill
- Tools
- Selective Tool Loading
- Read-Only Mode
- Other Clients

Why langfuse-mcp?

Langfuse is where your traces live. langfuse-mcp makes that telemetry directly usable by agents that need to answer questions like "what failed?", "why was this slow?", "which prompt version ran?", or "what happened in this user's session?"

Positioning relative to the native Langfuse MCP (as of June 2026):

| | langfuse-mcp | Native Langfuse MCP |
|-|--------------|---------------------|
| Primary fit | Local, debugging-first MCP server + agent skill | Hosted, zero-install endpoint backed by Langfuse |
| Deployment | Local stdio or HTTP, via the Langfuse Python SDK | Native streamable HTTP at /api/public/mcp |
| Trace / session / exception tools | First-class | Observation/API-oriented access |
| Route-decision tools | Yes | No |
| Token & output control | Compact summaries, truncation, file-dump mode, tool-group gating | Depends on the hosted tool response + client |
| Metrics & dataset runs | Yes | Yes |
| Prompt, dataset, queue & score reads | Yes | Yes |
| Score writes, comments, models, media | Not yet | Yes |

This project does not mirror every native Langfuse MCP tool. It focuses on agent debugging ergonomics — compact trace inspection, exception triage, session analysis, routing-decision workflows, local tool-group gating, and an included skill with ready-made investigation playbooks. Use the native MCP for the broad hosted API surface; use langfuse-mcp as a local, token-disciplined layer.

Quick Start

Requires uv (for uvx) and Python 3.10 or newer. CI verifies Python 3.10 through 3.14.

Get credentials from Langfuse Cloud → Settings → API Keys. If self-hosted, use your instance URL for LANGFUSE_HOST.

```bash

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

listTraces

getTrace

listObservations

getObservation

listSessions

getSession

listScores

getScore

listScoreConfigs

getScoreConfig

listPrompts

getPrompt

listDatasets

getDataset

listDatasetItems

getDatasetItem

listDatasetRuns

getDatasetRun

getMetrics

getDailyMetrics

listModels

getModel

listProjects

listComments

getComment

getMedia

getHealth

Claude Desktop / Cursor

McpServers

Langfuse MCP Server

What You Can Do

Project Links

Why langfuse-mcp?

Quick Start

Install

More like this

Sequential Thinking

Sentry

Github

Filesystem

EverArt

Google Drive

`listTraces`

`getTrace`

`listObservations`

`getObservation`

`listSessions`

`getSession`

`listScores`

`getScore`

`listScoreConfigs`

`getScoreConfig`

`listPrompts`

`getPrompt`

`listDatasets`

`getDataset`

`listDatasetItems`

`getDatasetItem`

`listDatasetRuns`

`getDatasetRun`

`getMetrics`

`getDailyMetrics`

`listModels`

`getModel`

`listProjects`

`listComments`

`getComment`

`getMedia`

`getHealth`