langfuse-mcp

therealsachin/langfuse-mcp

3.2

If you are the rightful owner of langfuse-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

Langfuse MCP Server is a comprehensive tool for querying analytics, cost metrics, and usage data across multiple projects.

Tools
18
Resources
0
Prompts
0

Langfuse MCP Server

Version 1.4.2 - A secure MCP server for Langfuse analytics with comprehensive security features and dual readonly/readwrite modes for safe operation.

🔒 Security-First Design (New in v1.4.0)

  • Dual Operation Modes - Safe readonly mode by default, explicit opt-in for write operations
  • Triple-Layer Security - Environment, tool list, and runtime validation
  • Write Tool Prefixing - Clear write_* prefixes for all data modification operations
  • Confirmation Prompts - Required confirmation for destructive operations
  • Comprehensive Audit Logging - All write operations logged for compliance and security

Features

  • 32+ Comprehensive Tools - Complete analytics, dataset management, and comment collaboration
  • Secure Mode System - Readonly (default) and readwrite modes with explicit opt-in
  • Cost & Usage Analytics - Detailed breakdowns by model, service, environment, and time periods
  • Dataset Management - Create, organize, and manage test datasets with validation examples
  • Comment Collaboration - Add comments to traces, observations, sessions, and prompts
  • Trace Analysis & Debugging - Advanced filtering, search, and detailed trace inspection
  • System Management - Health monitoring, model management, and prompt template operations
  • Real-time Testing - Comprehensive test suite with mode validation

What's New in v1.4.0

🔒 Security & Mode System:

  • Readonly mode by default - only read operations allowed
  • Readwrite mode with explicit opt-in for data modification
  • Write tool prefixing (write_create_dataset, write_delete_dataset_item, etc.)
  • Confirmation prompts for destructive operations
  • Comprehensive audit logging for all write operations

🛠️ Enhanced Functionality:

  • 32+ tools across analytics, dataset management, and collaboration
  • Single CLI binary with intuitive mode flags: langfuse-mcp
  • Legacy tool support during transition period
  • Mode-aware tool filtering and descriptions

✅ Production Ready:

  • Triple-layer security validation
  • Extensive test coverage including mode validation
  • Clean error messages and user guidance
  • Structured audit logs for compliance

Installation

Option 1: Using npx (Recommended)

Read-Only Mode (Safe Default):

# Only analytics and read operations - safe for most users
npx @therealsachin/langfuse-mcp
# OR explicitly use readonly binary
langfuse-mcp-ro

Read-Write Mode (Explicit Opt-in):

# ⚠️ Enables write operations - can modify your Langfuse data
LANGFUSE_MCP_MODE=readwrite npx @therealsachin/langfuse-mcp
# OR use CLI flag
langfuse-mcp --readwrite

Option 2: Local Development

git clone https://github.com/therealsachin/langfuse-mcp.git
cd langfuse-mcp
npm install
npm run build

# Test readonly mode
LANGFUSE_MCP_MODE=readonly node build/index.js

# Test readwrite mode
LANGFUSE_MCP_MODE=readwrite node build/index.js

Configuration

Basic Configuration

Set environment variables for each Langfuse project:

LANGFUSE_PUBLIC_KEY=pk-lf-xxx
LANGFUSE_SECRET_KEY=sk-lf-xxx
LANGFUSE_BASEURL=https://us.cloud.langfuse.com

Mode Configuration (New in v1.4.1)

Control server operation mode using CLI flags or environment variables:

CLI Flags (Recommended for npx usage):

# Read-only mode (default, safe)
npx @therealsachin/langfuse-mcp

# Read-write mode (explicit opt-in)
npx @therealsachin/langfuse-mcp --readwrite

# Alternative explicit flag syntax
npx @therealsachin/langfuse-mcp --mode=readonly
npx @therealsachin/langfuse-mcp --mode=readwrite

Environment Variables (Legacy support):

# Readonly mode (default, safe)
LANGFUSE_MCP_MODE=readonly

# Readwrite mode (explicit opt-in)
LANGFUSE_MCP_MODE=readwrite

Claude Desktop Configuration

Read-Only Mode (Recommended for most users):

{
  "mcpServers": {
    "langfuse": {
      "command": "npx",
      "args": ["@therealsachin/langfuse-mcp"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-your-key",
        "LANGFUSE_SECRET_KEY": "sk-lf-your-secret",
        "LANGFUSE_BASEURL": "https://us.cloud.langfuse.com"
      }
    }
  }
}

Read-Write Mode (Advanced users only):

{
  "mcpServers": {
    "langfuse": {
      "command": "npx",
      "args": ["@therealsachin/langfuse-mcp", "--readwrite"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-your-key",
        "LANGFUSE_SECRET_KEY": "sk-lf-your-secret",
        "LANGFUSE_BASEURL": "https://us.cloud.langfuse.com"
      }
    }
  }
}

🔒 Security Best Practices

⚠️ IMPORTANT: Never commit real API credentials to version control!

Built-in Security Features (New in v1.4.2)

This MCP server includes multiple layers of security protection:

🛡️ HTTPS Enforcement
  • Automatic validation ensures all connections use HTTPS protocol
  • Prevents plaintext transmission of credentials and sensitive data
  • Runtime checks reject any HTTP URLs with clear error messages
  • Production safety guarantees secure communication with Langfuse APIs
🔍 URL Sanitization
  • Automatic redaction of sensitive query parameters in error logs
  • Information disclosure prevention protects against credential leakage in logs
  • Smart filtering preserves debugging info while removing secrets
  • Audit trail protection keeps logs clean and compliant
🚨 Pre-commit Security Hooks
  • Automated credential detection prevents accidental commits of real API keys
  • Langfuse-specific patterns scan for pk-lf- and sk-lf- format keys
  • General secret detection catches common credential patterns
  • Build validation ensures code compiles before commit
  • Git integration uses Husky for seamless workflow integration

To enable pre-commit hooks in your development environment:

npm install husky --save-dev
npx husky install
# Hooks are automatically configured - no manual setup needed!

Secure Credential Management

  1. Use Environment Variables: Store credentials in environment variables, never hardcode them in source files
  2. Use .env Files Locally: Create a .env file for local development (already in .gitignore)
  3. Use Placeholder Values: In committed files, use placeholders like pk-lf-your-public-key
  4. Rotate Keys Regularly: Periodically generate new API keys in your Langfuse dashboard
  5. Limit Key Permissions: Use project-specific keys with minimal required permissions

What NOT to do:

# ❌ NEVER commit real credentials like this:
LANGFUSE_PUBLIC_KEY=pk-lf-REAL-KEY-NEVER-COMMIT-THIS
LANGFUSE_SECRET_KEY=sk-lf-REAL-SECRET-NEVER-COMMIT-THIS

What TO do:

# ✅ Use placeholder values in committed files:
LANGFUSE_PUBLIC_KEY=pk-lf-your-actual-public-key
LANGFUSE_SECRET_KEY=sk-lf-your-actual-secret-key

# ✅ Store real credentials in .env file (never committed):
# Create a .env file in your project root with your actual credentials

For Production Deployments:

  • Use secure environment variable management (e.g., Kubernetes Secrets, Docker secrets, cloud provider secret managers)
  • Never include credentials in Docker images or CI/CD logs
  • Use least-privilege access principles

Available Tools (18 Total)

Core Analytics Tools (6)

  1. list_projects - List all configured Langfuse projects
  2. project_overview - Get cost, tokens, and trace summary for a project
  3. usage_by_model - Break down usage and cost by AI model
  4. usage_by_service - Analyze usage by service/feature tag
  5. top_expensive_traces - Find the most expensive traces
  6. get_trace_detail - Get detailed information about a specific trace

Extended Analytics Tools (6)

  1. get_projects - Alias for list_projects (list available Langfuse projects)
  2. get_metrics - Query aggregated metrics (costs, tokens, counts) with flexible filtering
  3. get_traces - Fetch traces with comprehensive filtering options
  4. get_observations - Get LLM generations/spans with details and filtering
  5. get_cost_analysis - Specialized cost breakdowns by model/user/daily trends
  6. get_daily_metrics - Daily usage trends and patterns with averages

System & Management Tools (6)

  1. get_observation_detail - Get detailed information about a specific observation/generation
  2. get_health_status - Monitor Langfuse system health and status
  3. list_models - List all AI models available in the project
  4. get_model_detail - Get detailed information about a specific AI model
  5. list_prompts - List all prompt templates with filtering and pagination
  6. get_prompt_detail - Get detailed information about a specific prompt template

Usage with Claude Desktop

Add to your claude_desktop_config.json:

Option 1: Using npx (Recommended)

{
  "mcpServers": {
    "langfuse-analytics": {
      "command": "npx",
      "args": ["@therealsachin/langfuse-mcp"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-xxx",
        "LANGFUSE_SECRET_KEY": "sk-lf-xxx",
        "LANGFUSE_BASEURL": "https://us.cloud.langfuse.com"
      }
    }
  }
}

Option 2: Local Installation

{
  "mcpServers": {
    "langfuse-analytics": {
      "command": "node",
      "args": ["/path/to/langfuse-mcp/build/index.js"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-xxx",
        "LANGFUSE_SECRET_KEY": "sk-lf-xxx",
        "LANGFUSE_BASEURL": "https://us.cloud.langfuse.com"
      }
    }
  }
}

Example Queries

Once integrated with Claude Desktop, you can ask questions like:

Analytics Queries

  • "Show me the cost overview for the last 7 days"
  • "Which AI models are most expensive this month?"
  • "Find the top 10 most expensive traces from yesterday"
  • "Break down usage by service for the production environment"
  • "Show me details for trace xyz-123"

System Management Queries

  • "Check the health status of my Langfuse system"
  • "List all available AI models in my project"
  • "Show me details for the GPT-4 model"
  • "What prompt templates do I have available?"
  • "Get details for the 'customer-support' prompt"

Advanced Analysis

  • "Show me detailed information for observation abc-123"
  • "What's the daily cost trend for the last month?"
  • "Find all traces that cost more than $0.10"
  • "Which users are generating the highest costs?"

Development

# Watch mode for development
npm run watch

# Test with MCP Inspector
npm run inspector

# Test endpoints (requires .env file)
npm run test

Testing with Real Langfuse Data

For comprehensive testing against real Langfuse data, create a .env file in the project root:

# .env file (never commit this - it's in .gitignore)
LANGFUSE_PUBLIC_KEY=pk-lf-your-actual-public-key
LANGFUSE_SECRET_KEY=sk-lf-your-actual-secret-key
LANGFUSE_BASEURL=https://us.cloud.langfuse.com

The test suite (npm run test) will automatically load these credentials using dotenv and run 13 comprehensive tests against your actual Langfuse project:

  • ✅ Project overview with real cost/token data
  • ✅ Trace retrieval with server-side sorting
  • ✅ Top expensive traces analysis
  • ✅ Daily metrics aggregation
  • ✅ Cost analysis breakdowns
  • ✅ Health status monitoring
  • ✅ Model and prompt management
  • ✅ Observation detail retrieval

Note: The .env file is automatically ignored by git to keep your credentials secure.

Publishing to NPM

✅ Package Published! The package is available via:

# Install and run directly with npx
npx @therealsachin/langfuse-mcp

# Or install globally
npm install -g @therealsachin/langfuse-mcp

Package Information:

Project Structure

src/
├── index.ts              # Main server entry point
├── config.ts             # Project configuration loader
├── langfuse-client.ts    # Langfuse client wrapper with 18+ API methods
├── types.ts              # TypeScript type definitions
└── tools/                # All 18 MCP tools
    # Core Analytics Tools (6)
    ├── list-projects.ts
    ├── project-overview.ts
    ├── usage-by-model.ts
    ├── usage-by-service.ts
    ├── top-expensive-traces.ts
    ├── get-trace-detail.ts
    # Extended Analytics Tools (6)
    ├── get-projects.ts          # Alias for list-projects
    ├── get-metrics.ts           # Aggregated metrics
    ├── get-traces.ts            # Trace filtering
    ├── get-observations.ts      # LLM generations
    ├── get-cost-analysis.ts     # Cost breakdowns
    ├── get-daily-metrics.ts     # Daily trends
    # System & Management Tools (6)
    ├── get-observation-detail.ts    # Observation details
    ├── get-health-status.ts         # Health monitoring
    ├── list-models.ts               # AI models listing
    ├── get-model-detail.ts          # Model details
    ├── list-prompts.ts              # Prompt templates
    └── get-prompt-detail.ts         # Prompt details

docs/                     # Comprehensive documentation
├── ARCHITECTURE.md       # System design and patterns
├── DEVELOPER_GUIDE.md    # Development workflows
├── TECHNICAL_DIAGRAMS.md # Visual system flows
├── IMPLEMENTATION_NOTES.md # API implementation details
└── DOCUMENTATION_INDEX.md # Navigation guide

test-endpoints.js         # Comprehensive test suite (13 tests)

API Integration

This server integrates with multiple Langfuse public API endpoints:

Core Analytics APIs

  • /api/public/metrics - Aggregated analytics using GET with JSON query parameter
  • /api/public/metrics/daily - Daily usage metrics and cost breakdowns
  • /api/public/traces - Trace listing, filtering, and individual trace retrieval
  • /api/public/observations - Detailed observation analysis and LLM generation metrics

System Management APIs

  • /api/public/observations/{id} - Individual observation details and metadata
  • /api/public/health - System health status and monitoring
  • /api/public/models - AI model listing and configuration
  • /api/public/prompts - Prompt template management and versioning

API Implementation Notes:

  • Metrics API: Uses GET method with URL-encoded JSON in the query parameter
  • Traces API: Supports advanced filtering, pagination, and ordering
  • Observations API: Provides detailed LLM generation and span data
  • Daily Metrics API: Specialized endpoint for daily aggregated usage statistics
  • Health API: Simple endpoint for system status monitoring
  • Models/Prompts APIs: Support pagination, filtering, and detailed retrieval

All authentication is handled server-side using Basic Auth with your Langfuse API keys.

Documentation

For detailed architecture, development guides, and technical diagrams, see the :

  • - System design, patterns, and implementation details
  • - Development workflows and common tasks
  • - Visual system flows and component diagrams
  • - Complete navigation guide

Troubleshooting

✅ Fixed: 405 Method Not Allowed Errors

Previous Issue: Earlier versions encountered "405 Method Not Allowed" errors due to incorrect API usage.

Solution: This has been FIXED in the current version by using the correct Langfuse API implementation:

  • Metrics API: Now uses GET method with URL-encoded JSON query parameter (correct approach)
  • Traces API: Uses the actual /api/public/traces endpoint with proper filtering
  • Observations API: Uses /api/public/observations endpoint with correct parameters
  • Daily Metrics: Uses specialized /api/public/metrics/daily endpoint

✅ Fixed: Cost Values Returning as Zero

Previous Issue: Cost analysis tools were returning zero values even when actual cost data existed.

Solution: This has been FIXED by correcting field name mapping in API response parsing:

  • Metrics API Response Structure: The API returns aggregated field names like totalCost_sum, count_count, totalTokens_sum
  • Updated Field Access: All tools now use correct aggregated field names instead of direct field names
  • Daily Metrics Integration: Cost analysis now uses getDailyMetrics API for cleaner daily cost breakdowns
  • Affected Tools: get-cost-analysis, get-metrics, usage-by-model, usage-by-service, project-overview, get-daily-metrics

✅ Fixed: Response Size and API Parameter Issues

Previous Issues:

  1. get_observations returning responses exceeding MCP token limits (200k+ tokens)
  2. get_traces returning 400 Bad Request errors

Solutions Applied:

  • get_observations Response Size Control:
    • Added includeInputOutput: false parameter (default) to exclude large prompt/response content
    • Added truncateContent: 500 parameter to limit content size when included
    • Reduced default limit from 25 to 10 observations
    • Content truncation for input/output fields when enabled
  • get_traces API Parameter Fixes:
    • Added parameter validation for orderBy field
    • Enhanced error logging with full request details for debugging
    • Added proper error handling with detailed error responses

✅ Fixed: Cost Analysis Data Aggregation

Previous Issue: Cost analysis was showing zero values for total costs and model breakdowns while daily data worked correctly.

Root Cause: The Metrics API field mapping was still incorrect despite earlier fixes.

Solution: Switched to using the working Daily Metrics API data for all aggregations:

  • Total Cost Calculation: Now sums from daily data instead of broken metrics API
  • Model Breakdown: Extracts and aggregates model costs from daily usage data
  • Daily Breakdown: Optimized to reuse already-fetched daily data
  • User Breakdown: Still uses metrics API but with enhanced debugging

Result:

  • ✅ totalCost now shows correct values (sum of daily costs)
  • ✅ byModel now populated with real model cost breakdowns
  • ✅ byDay continues to work perfectly
  • 🔍 byUser includes debugging to identify any remaining field mapping issues

✅ Fixed: usage_by_model Showing Zero Costs/Tokens

Previous Issue: usage_by_model showed observation counts correctly but all costs and tokens as zero.

Root Cause: Same metrics API field mapping issue affecting cost calculations.

Solution: Applied the same daily metrics approach used in cost analysis:

  • Primary Method: Uses getDailyMetrics API to aggregate model costs and tokens from daily usage breakdowns
  • Fallback Method: Falls back to original metrics API with enhanced debugging if daily API fails
  • Data Aggregation: Properly extracts totalCost, totalUsage, and countObservations from daily data

Result:

  • ✅ Models now show real totalCost values instead of 0
  • ✅ Models now show real totalTokens values instead of 0
  • ✅ observationCount continues to work correctly

Performance Considerations

API Efficiency: The server now uses native Langfuse endpoints efficiently:

  • Metrics queries are processed server-side by Langfuse for optimal performance
  • Trace and observation filtering happens at the API level to reduce data transfer
  • Daily metrics use the specialized endpoint for pre-aggregated data

Environment Variables

Make sure these environment variables are properly set:

LANGFUSE_PUBLIC_KEY=pk-lf-xxx     # Your Langfuse public key
LANGFUSE_SECRET_KEY=sk-lf-xxx     # Your Langfuse secret key
LANGFUSE_BASEURL=https://us.cloud.langfuse.com  # Your Langfuse instance URL