Skip to content
Back to search

langfuse

Langfuse observability - query traces, debug exceptions, analyze sessions, manage prompts via MCP tools

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/avivsinai/langfuse-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/avivsinai/langfuse-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/avivsinai--langfuse-mcp/badge.svg)](/listings/avivsinai--langfuse-mcp)

HTML

<a href="/listings/avivsinai--langfuse-mcp"><img src="/api/listings/avivsinai--langfuse-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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`.

# 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).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/plugin.json · Manifest · 23 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "langfuse",
  3. "version": "0.14.0",
  4. "description": "Langfuse observability - query traces, debug exceptions, analyze sessions, manage prompts via MCP tools",
  5. "author": {
  6. "name": "Aviv Sinai",
  7. "url": "https://github.com/avivsinai"
  8. },
  9. "repository": "https://github.com/avivsinai/langfuse-mcp",
  10. "homepage": "https://github.com/avivsinai/langfuse-mcp#skills",
  11. "license": "MIT",
  12. "skills": "./skills/",
  13. "keywords": [
  14. "langfuse",
  15. "observability",
  16. "traces",
  17. "llm",
  18. "prompts",
  19. "debugging",
  20. "mcp",
  21. "telemetry"
  22. ]
  23. }
README.md · README · 365 lines · 2 findings marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Langfuse MCP Server
  2. <!-- mcp-name: io.github.avivsinai/langfuse-mcp -->
  3. [![PyPI](https://badge.fury.io/py/langfuse-mcp.svg)](https://badge.fury.io/py/langfuse-mcp)
  4. [![GitHub stars](https://img.shields.io/github/stars/avivsinai/langfuse-mcp)](https://github.com/avivsinai/langfuse-mcp/stargazers)
  5. [![PyPI downloads](https://img.shields.io/pypi/dm/langfuse-mcp)](https://pypistats.org/packages/langfuse-mcp)
  6. [![Downloads](https://static.pepy.tech/badge/langfuse-mcp)](https://pepy.tech/projects/langfuse-mcp)
  7. [![Python 3.10–3.14](https://img.shields.io/badge/python-3.10–3.14-blue.svg)](https://www.python.org/downloads/)
  8. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  9. **Usage:** [12,518 PyPI downloads last month](https://pypistats.org/packages/langfuse-mcp) ([pypistats](https://pypistats.org/api/packages/langfuse-mcp/recent), 2026-08-19). [v0.10.1](https://pypi.org/project/langfuse-mcp/0.10.1/).
  10. Local [MCP](https://modelcontextprotocol.io) server and skill for [Langfuse](https://langfuse.com). Debug traces, sessions, and exceptions from Claude Code, Codex, Cursor, or any MCP client.
  11. ## Why this instead of native Langfuse MCP?
  12. Use this for local debug: first-class traces, sessions, and exceptions; route-decision tools; compact / file-dump output; plus the included [`langfuse` skill](skills/langfuse/SKILL.md).
  13. Use official [Langfuse MCP](https://langfuse.com/docs/api-and-data-platform/features/mcp-server) for hosted, zero-install access to the broader API (score writes, comments, models, media).
  14. As of June 2026:
  15. | | langfuse-mcp | Native Langfuse MCP |
  16. |-|--------------|---------------------|
  17. | **Primary fit** | Local debug: traces, sessions, exceptions | Hosted, zero-install API surface |
  18. | **Deployment** | Local `stdio` or HTTP, via the Langfuse Python SDK | Native streamable HTTP at `/api/public/mcp` |
  19. | **Trace / session / exception tools** | First-class | Observation/API-oriented access |
  20. | **Route-decision tools** | Yes | No |
  21. | **Token & output control** | Compact summaries, truncation, file-dump mode, tool-group gating | Hosted tool response + client |
  22. | **Metrics & dataset runs** | Yes | Yes |
  23. | **Prompt, dataset, queue & score reads** | Yes | Yes |
  24. | **Score writes, comments, models, media** | No | Yes |
  25. `langfuse-mcp` for local debug. Native MCP for hosted breadth.
  26. ## See a failing trace in 2 minutes
  27. Install is `uvx langfuse-mcp` plus Langfuse API keys — [Quick Start](#quick-start) for Claude Code, Codex, Cursor, or Docker.
  28. After the client restarts, ask:
  29. ```text
  30. find exceptions in the last day
  31. ```
  32. That maps to existing tools:
  33. ```text
  34. find_exceptions(age=1440, group_by="file")
  35. find_exceptions_in_file(filepath="<file from the grouping>", age=1440)
  36. get_exception_details(trace_id="<trace_id from the file results>")
  37. ```
  38. `find_exceptions` returns `{group, count, observation_id, trace_id}` (top 50 groups) — each group carries a representative observation/trace ID, and `find_exceptions_in_file` also yields full error records. Then optionally:
  39. ```text
  40. fetch_trace(trace_id="<trace_id>", include_observations=true)
  41. ```
  42. The exception tools detect errors by observation `level == "ERROR"` (strict; a non-empty `status_message` alone does not count). Counts describe error-level observations, not individual exception events — `get_error_count.exception_count` is the same error-observation total reported by `find_exceptions.metadata.observation_count` (including groups beyond the top 50). Exception details come from recorded metadata (`exception.type` / `exception.message` / `exception.stacktrace`, top-level or under `metadata.attributes`); absent values are null. Results are not a point-in-time snapshot.
  43. ## Project Links
  44. - [Quick Start](#quick-start)
  45. - [Agent Skill](#agent-skill)
  46. - [Tools](#tools-48-total)
  47. - [Selective Tool Loading](#selective-tool-loading)
  48. - [Read-Only Mode](#read-only-mode)
  49. - [Other Clients](#other-clients)
  50. ## Quick Start
  51. 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.
  52. Get credentials from [Langfuse Cloud](https://cloud.langfuse.com) → Settings → API Keys. If self-hosted, use your instance URL for `LANGFUSE_HOST`.
  53. ```bash
  54. # Claude Code (project-scoped, shared via .mcp.json)
  55. claude mcp add \
  56. -e LANGFUSE_PUBLIC_KEY=pk-... \
  57. -e LANGFUSE_SECRET_KEY=sk-... \
  58. -e LANGFUSE_HOST=https://cloud.langfuse.com \
  59. --scope project \
  60. langfuse -- uvx langfuse-mcp
  61. # Codex CLI (user-scoped, stored in ~/.codex/config.toml)
  62. codex mcp add langfuse \
  63. --env LANGFUSE_PUBLIC_KEY=pk-... \
  64. --env LANGFUSE_SECRET_KEY=sk-... \
  65. --env LANGFUSE_HOST=https://cloud.langfuse.com \
  66. -- uvx langfuse-mcp
  67. ```
  68. To pin a CI-verified interpreter explicitly, add `--python 3.14` before `langfuse-mcp`.
  69. Restart your CLI, then verify with `/mcp` (Claude Code) or `codex mcp list` (Codex).
  70. ## Agent Skill
  71. This repo ships a first-party [`langfuse` skill](skills/langfuse/SKILL.md) for Claude Code and Codex. The skill gives agents concrete playbooks for trace debugging, exception triage, latency analysis, prompt management, and dataset work.
  72. Install it when you want the agent to know when to reach for Langfuse and which MCP tools to call first.
  73. **Via [skills](https://github.com/vercel-labs/add-skill)** (recommended):
  74. ```bash
  75. npx skills add avivsinai/langfuse-mcp -g -y
  76. ```
  77. **Via [skild](https://skild.sh)**:
  78. ```bash
  79. npx skild install @avivsinai/langfuse -t claude -y
  80. ```
  81. **Manual install:**
  82. ```bash
  83. cp -r skills/langfuse ~/.claude/skills/ # Claude Code
  84. cp -r skills/langfuse ~/.codex/skills/ # Codex CLI
  85. ```
  86. After installing the skill, try:
  87. ```text
  88. help me debug langfuse traces
  89. find exceptions in the last day
  90. why was this user's session slow?
  91. ```
  92. The MCP server provides the tools; the skill provides the agent-facing workflow. See [`skills/langfuse/SKILL.md`](skills/langfuse/SKILL.md), [`skills/langfuse/references/setup.md`](skills/langfuse/references/setup.md), and [`skills/langfuse/references/tool-reference.md`](skills/langfuse/references/tool-reference.md).
  93. ## Tools (48 total)
  94. | Category | Tools |
  95. |----------|-------|
  96. | Traces | `fetch_traces`, `fetch_trace` |
  97. | Observations | `fetch_observations`, `fetch_observation` |
  98. | Routing | `find_route_decisions`, `get_route_decision`, `summarize_route_decisions`, `find_low_confidence_route_decisions` |
  99. | Sessions | `fetch_sessions`, `get_session_details`, `get_user_sessions` |
  100. | Exceptions | `find_exceptions`, `find_exceptions_in_file`, `get_exception_details`, `get_error_count` |
  101. | Prompts | `list_prompts`, `get_prompt`, `get_prompt_unresolved`, `create_text_prompt`, `create_chat_prompt`, `update_prompt_labels` |
  102. | Datasets | `list_datasets`, `get_dataset`, `list_dataset_items`, `get_dataset_item`, `create_dataset`, `create_dataset_item`, `delete_dataset_item`, `list_dataset_runs`, `get_dataset_run`, `list_dataset_run_items`, `create_dataset_run_item`, `delete_dataset_run` |
  103. | Annotation Queues | `list_annotation_queues`, `create_annotation_queue`, `get_annotation_queue`, `list_annotation_queue_items`, `get_annotation_queue_item`, `create_annotation_queue_item`, `update_annotation_queue_item`, `delete_annotation_queue_item`, `create_annotation_queue_assignment`, `delete_annotation_queue_assignment` |
  104. | Scores | `list_scores_v2`, `get_score_v2` |
  105. | Metrics | `query_metrics`, `get_metrics_schema` |
  106. | Schema | `get_data_schema` |
  107. On Observations API v2, traces are built from root observations. `fetch_traces` omits traces without a root observation, and `fetch_trace` cannot find traces with no observations.
  108. Dataset-run reads use the experiments API when the installed Langfuse SDK exposes it (Python SDK 4.13.1+). The older routes remain a fallback for self-hosted servers that do not serve experiments. `delete_dataset_run` uses the legacy delete route while it works; after that route is removed, it deletes the run's traces only when you pass `delete_traces=True`. Trace deletion also removes observations and related scores. `create_dataset_run_item` still uses the legacy link API; when that API is gone, create experiment data through the SDK experiment runner or OTel ingestion.
  109. ## Dataset Item Updates (Upsert)
  110. Langfuse uses upsert for dataset items. To edit an existing item, call `create_dataset_item` with `item_id`. If the ID exists, it updates; otherwise it creates a new item.
  111. ```python
  112. create_dataset_item(dataset_name="qa-test-cases", item_id="item_123", input={"question": "What is 2+2?"}, expected_output={"answer": "4"})
  113. ```
  114. ## Metrics Queries
  115. `query_metrics` aggregates telemetry server-side (cost, latency, tokens, counts, score values) so agents can answer "what did inference cost?" or "what's p95 latency by model?" without pulling raw traces. Call `get_metrics_schema` for the full view/dimension/measure catalog.
  116. ```python
  117. query_metrics(
  118. view="observations",
  119. metrics=[{"measure": "totalCost", "aggregation": "sum"}, {"measure": "latency", "aggregation": "p95"}],
  120. dimensions=["providedModelName"],
  121. age=1440, # last 24h; or pass from_timestamp / to_timestamp
  122. )
  123. ```
  124. High-cardinality fields (`id`, `traceId`, `userId`, `sessionId`) must be used in `filters`, not `dimensions`. The v2 metrics endpoint is Langfuse Cloud-only; self-hosted instances may return 404.
  125. ## Selective Tool Loading
  126. Load only the tool groups you need to reduce token overhead:
  127. ```bash
  128. langfuse-mcp --tools traces,prompts
  129. ```
  130. Available groups: `traces`, `observations`, `routing`, `sessions`, `exceptions`, `prompts`, `datasets`, `annotation_queues`, `scores`, `metrics`, `schema`
  131. The `routing` group is router-neutral. It reads Langfuse span observations with
  132. `metadata.schema_version: "mcp.route_decision.v1"` and filters on route-decision
  133. fields stored in observation metadata, such as `decision_id`, `router_name`,
  134. `provider`, and `capability_id`.
  135. ## Read-Only Mode
  136. Disable all write operations for safer read-only access:
  137. ```bash
  138. langfuse-mcp --read-only
  139. # Or via environment variable
  140. LANGFUSE_MCP_READ_ONLY=true langfuse-mcp
  141. ```
  142. This disables: `create_text_prompt`, `create_chat_prompt`, `update_prompt_labels`, `create_dataset`, `create_dataset_item`, `delete_dataset_item`, `create_dataset_run_item`, `delete_dataset_run`, `create_annotation_queue`, `create_annotation_queue_item`, `update_annotation_queue_item`, `delete_annotation_queue_item`, `create_annotation_queue_assignment`, `delete_annotation_queue_assignment`
  143. ## Default Output Mode
  144. Set the MCP-exposed default `output_mode` so clients that omit the parameter automatically use your preferred mode:
  145. ```bash
  146. langfuse-mcp --default-output-mode full_json_file
  147. # Or via environment variable
  148. LANGFUSE_MCP_DEFAULT_OUTPUT_MODE=full_json_file langfuse-mcp
  149. ```
  150. Supported values: `compact`, `full_json_string`, `full_json_file`
  151. This updates the default shown in MCP tool schemas. Clients can still override it per call by passing `output_mode` explicitly.
  152. ## Other Clients
  153. ### Cursor
  154. Create `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for global):
  155. ```json
  156. {
  157. "mcpServers": {
  158. "langfuse": {
  159. "command": "uvx",
  160. "args": ["langfuse-mcp"],
  161. "env": {
  162. "LANGFUSE_PUBLIC_KEY": "pk-...",
  163. "LANGFUSE_SECRET_KEY": "sk-...",
  164. "LANGFUSE_HOST": "https://cloud.langfuse.com",
  165. "LANGFUSE_MCP_DEFAULT_OUTPUT_MODE": "full_json_file"
  166. }
  167. }
  168. }
  169. }
  170. ```
  171. ### Docker (single project)
  172. ```bash
  173. docker run --rm -i \
  174. -e LANGFUSE_PUBLIC_KEY=pk-... \
  175. -e LANGFUSE_SECRET_KEY=sk-... \
  176. -e LANGFUSE_HOST=https://cloud.langfuse.com \
  177. ghcr.io/avivsinai/langfuse-mcp:latest
  178. ```
  179. ### Multiple projects with profiles (stdio)
  180. For local clients (Claude Code, Codex, Cursor), keep the credentials of each Langfuse
  181. project in a profiles file and register one MCP server per project. Each server
  182. starts with `--profile <name>`.
  183. The file is TOML at `$XDG_CONFIG_HOME/langfuse-mcp/profiles.toml` (or
  184. `~/.config/langfuse-mcp/profiles.toml` when `XDG_CONFIG_HOME` is not set). Use
  185. `--profiles-file PATH` or `LANGFUSE_MCP_PROFILES_FILE` to read a different file.
  186. ```toml
  187. [profiles.prod]
  188. host = "https://cloud.langfuse.com"
  189. public_key = "pk-lf-..."
  190. secret_key_env = "LANGFUSE_PROD_SECRET_KEY" # read the secret from this env var
  191. [profiles.staging]
  192. host = "https://langfuse.staging.example.com"
  193. public_key = "pk-lf-..."
  194. secret_key = "sk-lf-..." # or give the value directly
  195. ```
  196. Each of `public_key`, `secret_key` and `host` takes a literal value, or a
  197. `<field>_env` key that names the environment variable that holds the value.
  198. `host` defaults to `https://cloud.langfuse.com`.
  199. ```bash
  200. claude mcp add langfuse-prod -- uvx langfuse-mcp --profile prod
  201. claude mcp add langfuse-staging -- uvx langfuse-mcp --profile staging
  202. ```
  203. ```json
  204. {
  205. "mcpServers": {
  206. "langfuse-prod": {
  207. "command": "uvx",
  208. "args": ["langfuse-mcp", "--profile", "prod"]
  209. },
  210. "langfuse-staging": {
  211. "command": "uvx",
  212. "args": ["langfuse-mcp", "--profile", "staging"]
  213. }
  214. }
  215. }
  216. ```
  217. Precedence is CLI flags (`--public-key`, `--secret-key`, `--host`) > environment
  218. variables (`LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, `LANGFUSE_HOST`) > the
  219. selected profile > defaults. When an environment variable overrides a profile
  220. value, the server logs a warning. An unknown profile name or a missing profiles
  221. file stops the server with an error that names the file and the available
  222. profiles. `LANGFUSE_MCP_PROFILE` selects a profile when `--profile` is not given.
  223. ### HTTP transport — shared server for multiple projects
  224. Run one persistent server instance and route each MCP client to its own Langfuse
  225. project by passing credentials in the `Authorization` header.
  226. ```bash
  227. # Start a shared server (binds to localhost by default)
  228. docker run -d -p 127.0.0.1:8000:8000 \
  229. -e LANGFUSE_HOST=https://cloud.langfuse.com \
  230. ghcr.io/avivsinai/langfuse-mcp:latest \
  231. --transport streamable-http --bind-host 0.0.0.0
  232. ```
  233. > **Security note:** `--bind-host 0.0.0.0` exposes the port on all interfaces. In
  234. > production, place the server behind a TLS-terminating reverse proxy (nginx, Caddy,
  235. > Cloudflare Tunnel) that enforces HTTPS. The `Authorization` header containing your
  236. > keys is transmitted in plaintext over plain HTTP. If startup credentials are set,
  237. > the proxy must enforce authentication; otherwise unauthenticated callers without an
  238. > `Authorization` header can use the default project. For shared public HTTP deployments,
  239. > omit default `LANGFUSE_PUBLIC_KEY` / `LANGFUSE_SECRET_KEY` credentials unless the
  240. > fronting proxy authenticates every request.
  241. Register each project separately in your MCP client, passing its credentials as a
  242. `Basic` auth header (`base64(public_key:secret_key)`):
  243. ```bash
  244. # Generate the header value for each project:
  245. echo -n "pk-lf-YOURKEY:sk-lf-YOURSECRET" | base64
  246. # cGstbGYtWU9VUktFWTpzay1sZi1ZT1VSU0VDUkVU
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 329 on GitHub
  247. # Register in Claude Code (one entry per project):
  248. claude mcp add langfuse-audit \
  249. --transport http http://localhost:8000/mcp \
  250. -H "Authorization: Basic cGstbGYtWU9VUktFWTpzay1sZi1ZT1VSU0VDUkVU"
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 334 on GitHub
  251. claude mcp add langfuse-staging \
  252. --transport http http://localhost:8000/mcp \
  253. -H "Authorization: Basic <base64 for staging project>"
  254. ```
  255. **Auth semantics:** `Basic` here carries Langfuse API keys, not user passwords. An
  256. absent header falls back to startup env credentials (`LANGFUSE_PUBLIC_KEY` /
  257. `LANGFUSE_SECRET_KEY`). Any malformed header is rejected outright — there is no
  258. silent fallback to a different project.
  259. ### Optional environment variables
  260. | Variable | Default | Description |
  261. |---|---|---|
  262. | `LANGFUSE_MAX_AGE_DAYS` | `7` | Caps the lookback window for time-based tools (`fetch_traces`, `fetch_observations`, etc.). Set to match your Langfuse instance's data retention — e.g. `30` if your retention is 30 days. |
  263. | `LANGFUSE_MCP_PROFILE` | unset | Profile to load from the profiles file; same as `--profile`. See [Multiple projects with profiles](#multiple-projects-with-profiles-stdio). |
  264. | `LANGFUSE_MCP_PROFILES_FILE` | `$XDG_CONFIG_HOME/langfuse-mcp/profiles.toml` | Path of the profiles file; same as `--profiles-file`. |
  265. | `LANGFUSE_MCP_TRACE_TIMEOUT_SECONDS` | `120` | Per-request read timeout (seconds) for single-trace fetches (`fetch_trace`). Raise it if large traces with `include_observations=True` time out. Must be a positive integer. |
  266. ## Development
  267. ```bash
  268. uv venv --python 3.14 .venv && source .venv/bin/activate
  269. uv pip install -e ".[dev]"
  270. pytest
  271. ```
  272. ## License
  273. MIT

Version history

  • v0.14.010/26/2026

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.