接入你的智能体
发布者自己的命令。不是 PlugMCP 端点。
用我们的密钥与日志托管一份副本。
uvx langfuse-mcp==0.14.0Claude Code 没有针对本地命令的安装链接。复制下方命令并在终端中运行。
LANGFUSE_PUBLIC_KEY=<secret> LANGFUSE_SECRET_KEY=<secret> LANGFUSE_HOST=<value> LANGFUSE_MCP_READ_ONLY=<value> claude mcp add avivsinai-langfuse-mcp -- uvx langfuse-mcp==0.14.0在终端中运行。
{ "mcpServers": { "avivsinai-langfuse-mcp": { "command": "uvx", "args": [ "langfuse-mcp==0.14.0" ], "env": { "LANGFUSE_PUBLIC_KEY": "<secret>", "LANGFUSE_SECRET_KEY": "<secret>", "LANGFUSE_HOST": "<value>", "LANGFUSE_MCP_READ_ONLY": "<value>" } } }}claude_desktop_config.json
远程 URL 还是本机命令? 两种安装方式的区别
Usage: 12,518 PyPI downloads last month (pypistats, 2026-08-19). v0.10.1.
Local MCP server and skill for Langfuse. Debug traces, sessions, and exceptions from Claude Code, Codex, Cursor, or any MCP client.
Use this for local debug: first-class traces, sessions, and exceptions; route-decision tools; compact / file-dump output; plus the included langfuse skill.
Use official Langfuse MCP for hosted, zero-install access to the broader API (score writes, comments, models, media).
As of June 2026:
langfuse-mcp for local debug. Native MCP for hosted breadth.
Install is uvx langfuse-mcp plus Langfuse API keys — Quick Start for Claude Code, Codex, Cursor, or Docker.
After the client restarts, ask:
find exceptions in the last day
That maps to existing tools:
find_exceptions(age=1440, group_by="file")
find_exceptions_in_file(filepath="<file from the grouping>", age=1440)
get_exception_details(trace_id="<trace_id from the file results>")
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:
fetch_trace(trace_id="<trace_id>", include_observations=true)
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.
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.
# 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).
This repo ships a first-party langfuse skill for Claude Code and Codex. The skill gives agents concrete playbooks for trace debugging, exception triage, latency analysis, prompt management, and dataset work.
Install it when you want the agent to know when to reach for Langfuse and which MCP tools to call first.
Via skills (recommended):
npx skills add avivsinai/langfuse-mcp -g -y
Via skild:
npx skild install @avivsinai/langfuse -t claude -y
Manual install:
cp -r skills/langfuse ~/.claude/skills/ # Claude Code
cp -r skills/langfuse ~/.codex/skills/ # Codex CLI
After installing the skill, try:
help me debug langfuse traces
find exceptions in the last day
why was this user's session slow?
The MCP server provides the tools; the skill provides the agent-facing workflow. See skills/langfuse/SKILL.md, skills/langfuse/references/setup.md, and skills/langfuse/references/tool-reference.md.
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.
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.
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.
create_dataset_item(dataset_name="qa-test-cases", item_id="item_123", input={"question": "What is 2+2?"}, expected_output={"answer": "4"})
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.
query_metrics(
view="observations",
metrics=[{"measure": "totalCost", "aggregation": "sum"}, {"measure": "latency", "aggregation": "p95"}],
dimensions=["providedModelName"],
age=1440, # last 24h; or pass from_timestamp / to_timestamp
)
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.
Load only the tool groups you need to reduce token overhead:
langfuse-mcp --tools traces,prompts
Available groups: traces, observations, routing, sessions, exceptions, prompts, datasets, annotation_queues, scores, metrics, schema
The routing group is router-neutral. It reads Langfuse span observations with
metadata.schema_version: "mcp.route_decision.v1" and filters on route-decision
fields stored in observation metadata, such as decision_id, router_name,
provider, and capability_id.
Disable all write operations for safer read-only access:
langfuse-mcp --read-only
# Or via environment variable
LANGFUSE_MCP_READ_ONLY=true langfuse-mcp
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
Set the MCP-exposed default output_mode so clients that omit the parameter automatically use your preferred mode:
langfuse-mcp --default-output-mode full_json_file
# Or via environment variable
LANGFUSE_MCP_DEFAULT_OUTPUT_MODE=full_json_file langfuse-mcp
Supported values: compact, full_json_string, full_json_file
This updates the default shown in MCP tool schemas. Clients can still override it per call by passing output_mode explicitly.
Create .cursor/mcp.json in your project (or ~/.cursor/mcp.json for global):
{
"mcpServers": {
"langfuse": {
"command": "uvx",
"args": ["langfuse-mcp"],
"env": {
"LANGFUSE_PUBLIC_KEY": "pk-...",
"LANGFUSE_SECRET_KEY": "sk-...",
"LANGFUSE_HOST": "https://cloud.langfuse.com",
"LANGFUSE_MCP_DEFAULT_OUTPUT_MODE": "full_json_file"
}
}
}
}
docker run --rm -i \
-e LANGFUSE_PUBLIC_KEY=pk-... \
-e LANGFUSE_SECRET_KEY=sk-... \
-e LANGFUSE_HOST=https://cloud.langfuse.com \
ghcr.io/avivsinai/langfuse-mcp:latest
For local clients (Claude Code, Codex, Cursor), keep the credentials of each Langfuse
project in a profiles file and register one MCP server per project. Each server
starts with --profile <name>.
The file is TOML at $XDG_CONFIG_HOME/langfuse-mcp/profiles.toml (or
~/.config/langfuse-mcp/profiles.toml when XDG_CONFIG_HOME is not set). Use
--profiles-file PATH or LANGFUSE_MCP_PROFILES_FILE to read a different file.
[profiles.prod]
host = "https://cloud.langfuse.com"
public_key = "pk-lf-..."
secret_key_env = "LANGFUSE_PROD_SECRET_KEY" # read the secret from this env var
[profiles.staging]
host = "https://langfuse.staging.example.com"
public_key = "pk-lf-..."
secret_key = "sk-lf-..." # or give the value directly
Each of public_key, secret_key and host takes a literal value, or a
<field>_env key that names the environment variable that holds the value.
host defaults to https://cloud.langfuse.com.
claude mcp add langfuse-prod -- uvx langfuse-mcp --profile prod
claude mcp add langfuse-staging -- uvx langfuse-mcp --profile staging
{
"mcpServers": {
"langfuse-prod": {
"command": "uvx",
"args": ["langfuse-mcp", "--profile", "prod"]
},
"langfuse-staging": {
"command": "uvx",
"args": ["langfuse-mcp", "--profile", "staging"]
}
}
}
Precedence is CLI flags (--public-key, --secret-key, --host) > environment
variables (LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_HOST) > the
selected profile > defaults. When an environment variable overrides a profile
value, the server logs a warning. An unknown profile name or a missing profiles
file stops the server with an error that names the file and the available
profiles. LANGFUSE_MCP_PROFILE selects a profile when --profile is not given.
Run one persistent server instance and route each MCP client to its own Langfuse
project by passing credentials in the Authorization header.
# Start a shared server (binds to localhost by default)
docker run -d -p 127.0.0.1:8000:8000 \
-e LANGFUSE_HOST=https://cloud.langfuse.com \
ghcr.io/avivsinai/langfuse-mcp:latest \
--transport streamable-http --bind-host 0.0.0.0
Security note:
--bind-host 0.0.0.0exposes the port on all interfaces. In production, place the server behind a TLS-terminating reverse proxy (nginx, Caddy, Cloudflare Tunnel) that enforces HTTPS. TheAuthorizationheader containing your keys is transmitted in plaintext over plain HTTP. If startup credentials are set, the proxy must enforce authentication; otherwise unauthenticated callers without anAuthorizationheader can use the default project. For shared public HTTP deployments, omit defaultLANGFUSE_PUBLIC_KEY/LANGFUSE_SECRET_KEYcredentials unless the fronting proxy authenticates every request.
Register each project separately in your MCP client, passing its credentials as a
Basic auth header (base64(public_key:secret_key)):
# Generate the header value for each project:
echo -n "pk-lf-YOURKEY:sk-lf-YOURSECRET" | base64
# cGstbGYtWU9VUktFWTpzay1sZi1ZT1VSU0VDUkVU
# Register in Claude Code (one entry per project):
claude mcp add langfuse-audit \
--transport http http://localhost:8000/mcp \
-H "Authorization: Basic cGstbGYtWU9VUktFWTpzay1sZi1ZT1VSU0VDUkVU"
claude mcp add langfuse-staging \
--transport http http://localhost:8000/mcp \
-H "Authorization: Basic <base64 for staging project>"
Auth semantics: Basic here carries Langfuse API keys, not user passwords. An
absent header falls back to startup env credentials (LANGFUSE_PUBLIC_KEY /
LANGFUSE_SECRET_KEY). Any malformed header is rejected outright — there is no
silent fallback to a different project.
uv venv --python 3.14 .venv && source .venv/bin/activate
uv pip install -e ".[dev]"
pytest
MIT
A Model Context Protocol (MCP) server for Langfuse, enabling AI agents to query Langfuse trace data for enhanced debugging and observability
{ "mcpServers": { "avivsinai-langfuse-mcp": { "command": "uvx", "args": [ "langfuse-mcp==0.14.0" ], "env": { "LANGFUSE_PUBLIC_KEY": "<secret>", "LANGFUSE_SECRET_KEY": "<secret>", "LANGFUSE_HOST": "<value>", "LANGFUSE_MCP_READ_ONLY": "<value>" } } }}工具
暂无工具列表。远程服务器在首次健康检查后会获得工具列表。
常见问题
在本页复制适用于 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 配置。它使用发布者的安装方式,而不是 PlugMCP 代理。
发布者列出了以下环境变量:LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_HOST, LANGFUSE_MCP_READ_ONLY。
Langfuse 通过 stdio 在本地运行。
上次检查时间:2026-10-27。 A Model Context Protocol (MCP) server for Langfuse, enabling AI agents to query Langfuse trace data for enhanced debugging and observability