Langfuse MCP Server (Extended)

Langfuse MCP Server (Extended)

A comprehensive Model Context Protocol (MCP) server for Langfuse, providing AI assistants with full access to traces, observations, scores, datasets, and sessions.

Prompt Management: This server focuses on observability data. For prompt management, Langfuse provides a built-in MCP server (GitHub). We're working on integrating both - see Contributing.

Features

• 22 tools for complete Langfuse observability access
• Traces: List, get, and delete traces with filtering and pagination
• Observations: Query generations, spans, and events with usage metrics
• Scores: Full CRUD operations for evaluation scores (numeric, categorical, boolean)
• Score Configs: Manage score configuration templates
• Datasets: Complete dataset management including items and evaluation runs
• Sessions: Access session data with associated traces
• Cloud & Self-hosted: Works with Langfuse Cloud (US/EU) and self-hosted instances

Quick Start

One-liner Installation (Claude Code)

claude mcp add langfuse -e LANGFUSE_PUBLIC_KEY=pk-lf-xxx -e LANGFUSE_SECRET_KEY=sk-lf-xxx -- npx -y langfuse-mcp-extended

For EU Cloud or self-hosted, add the base URL:

claude mcp add langfuse -e LANGFUSE_PUBLIC_KEY=pk-lf-xxx -e LANGFUSE_SECRET_KEY=sk-lf-xxx -e LANGFUSE_BASE_URL=https://eu.cloud.langfuse.com -- npx -y langfuse-mcp-extended

Installation by Client

Add to your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "langfuse": {
      "command": "npx",
      "args": ["-y", "langfuse-mcp-extended"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-...",
        "LANGFUSE_SECRET_KEY": "sk-lf-..."
      }
    }
  }
}

For EU Cloud or self-hosted, add LANGFUSE_BASE_URL:

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

Option 1: One-liner with environment variables

claude mcp add langfuse -e LANGFUSE_PUBLIC_KEY=pk-lf-xxx -e LANGFUSE_SECRET_KEY=sk-lf-xxx -- npx -y langfuse-mcp-extended

Option 2: Add to project's .mcp.json

{
  "mcpServers": {
    "langfuse": {
      "command": "npx",
      "args": ["-y", "langfuse-mcp-extended"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-...",
        "LANGFUSE_SECRET_KEY": "sk-lf-..."
      }
    }
  }
}

Option 3: Use shell environment variables

claude mcp add langfuse -- npx -y langfuse-mcp-extended

Then set in your shell profile (.bashrc, .zshrc, etc.):

export LANGFUSE_PUBLIC_KEY="pk-lf-..."
export LANGFUSE_SECRET_KEY="sk-lf-..."

Add to your Cursor MCP configuration:

• Project-specific: .cursor/mcp.json in your project directory
• Global: ~/.cursor/mcp.json in your home directory

{
  "mcpServers": {
    "langfuse": {
      "command": "npx",
      "args": ["-y", "langfuse-mcp-extended"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-...",
        "LANGFUSE_SECRET_KEY": "sk-lf-..."
      }
    }
  }
}

Or add via UI: File → Preferences → Cursor Settings → MCP

Add to .vscode/mcp.json in your workspace:

{
  "mcpServers": {
    "langfuse": {
      "command": "npx",
      "args": ["-y", "langfuse-mcp-extended"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-...",
        "LANGFUSE_SECRET_KEY": "sk-lf-..."
      }
    }
  }
}

npm install -g langfuse-mcp-extended

Then use langfuse-mcp-extended as the command instead of npx -y langfuse-mcp-extended.

Configuration

Required Environment Variables

Optional Environment Variables

Langfuse Instance URLs

API Reference

Pagination

All list operations use page-based pagination with a default limit of 10 items per page:

• page (number, optional): Page number, 1-indexed. Default: 1
• limit (number, optional): Items per page, max 100. Default: 10

Response Size Control

Get operations (getTrace, getSession, getObservation) support an includeIO parameter:

• includeIO (boolean, optional): Include input/output fields. Default: false

When includeIO is false (default), large input and output fields are stripped from responses to prevent exceeding LLM context limits. Set to true when you need the full payload.

listTraces

List traces with filtering and pagination.

Inputs:

• page (number, optional): Page number
• limit (number, optional): Items per page
• name (string, optional): Filter by trace name
• userId (string, optional): Filter by user ID
• sessionId (string, optional): Filter by session ID
• tags (string[], optional): Filter by tags (AND logic)
• fromTimestamp (string, optional): Start of time range (ISO 8601)
• toTimestamp (string, optional): End of time range (ISO 8601)
• environment (string, optional): Filter by environment
• orderBy (string, optional): Sort by timestamp, latency, or totalCost

getTrace

Get a specific trace with full details.

Inputs:

• traceId (string, required): The trace ID
• includeIO (boolean, optional): Include input/output fields. Default: false

Returns: Trace with observations and scores.

deleteTrace

Delete a trace.

Inputs:

• traceId (string, required): The trace ID to delete

listObservations

List observations (generations, spans, events) with cursor-based pagination.

Inputs:

• cursor (string, optional): Pagination cursor
• limit (number, optional): Items per page
• traceId (string, optional): Filter by trace ID
• name (string, optional): Filter by observation name
• type (string, optional): Filter by type: GENERATION, SPAN, EVENT
• parentObservationId (string, optional): Filter by parent
• fromStartTime (string, optional): Start of time range (ISO 8601)
• toStartTime (string, optional): End of time range (ISO 8601)
• userId (string, optional): Filter by user ID
• version (string, optional): Filter by version

getObservation

Get a specific observation with all details.

Inputs:

• observationId (string, required): The observation ID
• includeIO (boolean, optional): Include input/output fields. Default: false

Returns: Observation with usage, costs, and timing.

createScore

Create a score for a trace or observation.

Inputs:

• traceId (string, required): ID of the trace to score
• name (string, required): Score name (e.g., accuracy, relevance)
• value (number | string, required): Score value
• observationId (string, optional): ID of specific observation to score
• dataType (string, optional): NUMERIC, CATEGORICAL, or BOOLEAN
• comment (string, optional): Explanation of the score
• configId (string, optional): Score config ID for validation
• id (string, optional): Custom ID for idempotency

listScores

List scores with filtering.

Inputs:

• page, limit (pagination)
• traceId (string, optional): Filter by trace ID
• observationId (string, optional): Filter by observation ID
• name (string, optional): Filter by score name
• source (string, optional): Filter by source: API, ANNOTATION, EVAL
• dataType (string, optional): Filter by data type
• configId (string, optional): Filter by config ID
• fromTimestamp, toTimestamp (string, optional): Time range
• userId (string, optional): Filter by user ID
• operator (string, optional): Comparison operator: <, >, <=, >=, !=, =
• value (number, optional): Value to compare (requires operator)

getScore

Get a specific score.

Inputs:

• scoreId (string, required): The score ID

deleteScore

Delete a score.

Inputs:

• scoreId (string, required): The score ID to delete

createScoreConfig

Create a score configuration template.

Inputs:

• name (string, required): Unique config name
• dataType (string, required): NUMERIC, CATEGORICAL, or BOOLEAN
• minValue (number, optional): Minimum value (NUMERIC only)
• maxValue (number, optional): Maximum value (NUMERIC only)
• categories (array, optional): Category definitions (CATEGORICAL only)
• description (string, optional): Description

listScoreConfigs

List all score configurations.

Inputs:

• page, limit (pagination)

getScoreConfig

Get a specific score configuration.

Inputs:

• configId (string, required): The config ID

createDataset

Create a new dataset.

Inputs:

• name (string, required): Dataset name
• description (string, optional): Description
• metadata (object, optional): Additional metadata

listDatasets

List all datasets.

Inputs:

• page, limit (pagination)

getDataset

Get a dataset by name.

Inputs:

• datasetName (string, required): The dataset name

createDatasetItem

Create or update a dataset item.

Inputs:

• datasetName (string, required): Target dataset name
• input (any, required): Item input data
• expectedOutput (any, optional): Expected output
• metadata (object, optional): Item metadata
• sourceTraceId (string, optional): Source trace ID
• sourceObservationId (string, optional): Source observation ID
• id (string, optional): Custom ID for upsert

listDatasetItems

List items in a dataset.

Inputs:

• datasetName (string, required): Dataset name
• page, limit (pagination)
• sourceTraceId (string, optional): Filter by source trace
• sourceObservationId (string, optional): Filter by source observation

getDatasetItem

Get a specific dataset item.

Inputs:

• datasetItemId (string, required): The item ID

deleteDatasetItem

Delete a dataset item.

Inputs:

• datasetItemId (string, required): The item ID to delete

createDatasetRunItem

Link a trace/observation to a dataset item for evaluation.

Inputs:

• runName (string, required): Name of the dataset run
• datasetItemId (string, required): Dataset item ID
• traceId (string, required): Trace ID
• runDescription (string, optional): Run description
• observationId (string, optional): Observation ID
• metadata (object, optional): Run item metadata

listDatasetRuns

List runs for a dataset.

Inputs:

• datasetName (string, required): Dataset name
• page, limit (pagination)

getDatasetRun

Get a specific dataset run.

Inputs:

• datasetName (string, required): Dataset name
• runName (string, required): Run name

listSessions

List all sessions.

Inputs:

• page, limit (pagination)
• fromTimestamp (string, optional): Start of time range (ISO 8601)
• toTimestamp (string, optional): End of time range (ISO 8601)

getSession

Get a specific session with its traces.

Inputs:

• sessionId (string, required): The session ID
• includeIO (boolean, optional): Include input/output in traces. Default: false

Returns: Session with associated traces.

Using with Official Langfuse MCP (Prompts)

This server provides observability tools (traces, scores, datasets). For prompt management, Langfuse provides a built-in MCP server that requires no installation.

Built-in Langfuse MCP (Recommended)

The Langfuse MCP server is built directly into Langfuse at /api/public/mcp. See the official documentation for setup instructions.

Using Both Servers Together

To use Langfuse observability (this server) alongside the official prompts MCP:

{
  "mcpServers": {
    "langfuse-observability": {
      "command": "npx",
      "args": ["-y", "langfuse-mcp-extended"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-...",
        "LANGFUSE_SECRET_KEY": "sk-lf-..."
      }
    }
  }
}

Then configure the built-in Langfuse prompts MCP following the official guide.

Note: We're actively working with the Langfuse team to potentially integrate both servers. See Contributing for details.

Development

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

# Run tests
npm test                  # Unit tests (59 tests)
npm run test:integration  # Integration tests (18 tests)
npm run test:all          # All tests

# Quality checks
npm run lint
npm run typecheck

Contributing

Contributions are welcome! This project aims to be integrated into the official Langfuse ecosystem.

Active discussions:

• langfuse/langfuse#5646 - Integration discussion
• langfuse/mcp-server-langfuse#14 - Feature request

How to contribute:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Author

Built by Javier Aguilar - AI Agent Architect specializing in multi-agent orchestration and MCP development.

License

MIT License - see LICENSE for details.

Related

• Langfuse - Open source LLM observability
• Langfuse MCP Server (Prompts) - Built-in prompt management MCP
• Model Context Protocol - MCP specification
• MCP Servers Registry - Official MCP servers