hugoles/langfuse-mcp

An MCP server that exposes the Langfuse REST API as tools, so Claude (or any MCP client) can query your traces, observations, sessions, scores, prompts, datasets, and metrics during a conversation.
Useful when you want to ask things like:
- _"Why did trace abc123 fail? Walk me through its observations."_
- _"List the 5 most recent traces with level=ERROR for user alice@x.com."_
- _"Summarize today's generation cost broken down by model."_
- _"Show me the production version of prompt customer-support-v2."_
…without leaving your assistant.
Requirements
- **Node.js 20 or newer** (node --version).
- A Langfuse project with API keys (cloud.langfuse.com → Settings → API Keys on EU cloud, us.cloud.langfuse.com on US cloud, or your self-hosted instance).
Tools
All tools are read-only and call the Langfuse Public API over HTTPS using your project keys for Basic Auth.
Traces & observations
| Tool | Description |
| ------------------ | --------------------------------------------------------------- |
| listTraces | List traces with filters. Returns summary metadata. |
| getTrace | Fetch a single trace by id including the full observation tree. |
| listObservations | List spans, generations, and events with filters. |
| getObservation | Fetch a single observation by id. |
Sessions
| Tool | Description |
| -------------- | -------------------------------------------- |
| listSessions | List sessions within a time range. |
| getSession | Fetch a session by id, including its traces. |
Scores
| Tool | Description |
| ------------------ | ------------------------------------------------------------ |
| listScores | List scores with filters. |
| getScore | Fetch a single score by id. |
| listScoreConfigs | List score configurations (definitions, ranges, categories). |
| getScoreConfig | Fetch a score configuration by id. |
Prompts
| Tool | Description |
| ------------- | ------------------------------------------------------------------------- |
| listPrompts | List prompt definitions, optionally filtered by name, label, or tag. |
| getPrompt | Fetch a prompt by name, optionally pinned to a specific version or label. |
Datasets
| Tool | Description |
| ------------------ | ------------------------------------------------------------- |
| listDatasets | List datasets configured in Langfuse. |
| getDataset | Fetch a dataset by name. |
| listDatasetItems | List items in a dataset (inputs, expected outputs, metadata). |
| getDatasetItem | Fetch a single dataset item by id. |
| listDatasetRuns | List evaluation runs for a dataset. |
| getDatasetRun | Fetch a specific dataset run by name. |
Metrics, models & misc
| Tool | Description |
| ----------------- | ------------------------------------------------------------------------------------------ |
| getMetrics | Run a custom metrics query (counts, latency, cost, token usage). Pass a JSON query string. |
| getDailyMetrics | Daily aggregated usage / cost / count metrics. |
| listModels | List models known to Langfuse (for cost / token attribution). |
| getModel | Fetch a model definition by id. |
| listProjects | List projects accessible to the current API key. |
| 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). |
| getHealth | Ping the Langfuse public health endpoint — useful for credential validation. |
Install
Zero install with npx:
Or install globally:
Configuration