Langfuse MCP 서버

PyPI Downloads Python 3.10–3.13 License: MIT

Langfuse 관측 가능성을 위한 Model Context Protocol 서버입니다. 트레이스 쿼리, 오류 디버깅, 세션 분석, 프롬프트 관리를 지원합니다.

왜 langfuse-mcp인가요?

공식 Langfuse MCP와의 비교 (2026년 1월 기준):

	langfuse-mcp	공식
트레이스 및 관측	예	아니요
세션 및 사용자	예	아니요
예외 추적	예	아니요
프롬프트 관리	예	예
데이터셋 관리	예	아니요
주석 큐	예	아니요
점수 (v2)	예	아니요
선택적 도구 로딩	예	아니요

이 프로젝트는 트레이스, 관측, 세션, 예외, 프롬프트, 데이터셋, 주석 큐, 점수 등 전체 관측 가능성 툴킷을 제공하며, 공식 MCP는 프롬프트 관리에 중점을 둡니다.

빠른 시작

uv (uvx용)가 필요합니다.

Langfuse Cloud → 설정 → API 키에서 자격 증명을 가져오세요. 자체 호스팅인 경우 LANGFUSE_HOST에 인스턴스 URL을 사용하세요.

# 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 --python 3.11 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 --python 3.11 langfuse-mcp

CLI를 재시작한 후 /mcp (Claude Code) 또는 codex mcp list (Codex)로 확인하세요.

도구 (총 37개)

카테고리	도구
트레이스	`fetch_traces`, `fetch_trace`
관측	`fetch_observations`, `fetch_observation`
세션	`fetch_sessions`, `get_session_details`, `get_user_sessions`
예외	`find_exceptions`, `find_exceptions_in_file`, `get_exception_details`, `get_error_count`
프롬프트	`list_prompts`, `get_prompt`, `get_prompt_unresolved`, `create_text_prompt`, `create_chat_prompt`, `update_prompt_labels`
데이터셋	`list_datasets`, `get_dataset`, `list_dataset_items`, `get_dataset_item`, `create_dataset`, `create_dataset_item`, `delete_dataset_item`
주석 큐	`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`
점수	`list_scores_v2`, `get_score_v2`
스키마	`get_data_schema`

데이터셋 항목 업데이트 (Upsert)

Langfuse는 데이터셋 항목에 대해 upsert를 사용합니다. 기존 항목을 수정하려면 item_id와 함께 create_dataset_item을 호출하세요. ID가 존재하면 업데이트되고, 그렇지 않으면 새 항목이 생성됩니다.

create_dataset_item(
  dataset_name="qa-test-cases",
  item_id="item_123",
  input={"question": "What is 2+2?"},
  expected_output={"answer": "4"}
)

스킬

이 프로젝트에는 디버깅 플레이북이 포함된 스킬이 있습니다.

skills를 통한 방법 (권장):

npx skills add avivsinai/langfuse-mcp -g -y

skild를 통한 방법:

npx skild install @avivsinai/langfuse -t claude -y

수동 설치:

cp -r skills/langfuse ~/.claude/skills/   # Claude Code
cp -r skills/langfuse ~/.codex/skills/    # Codex CLI

다음과 같이 질문해 보세요: "help me debug langfuse traces"

전체 문서는 skills/langfuse/SKILL.md를 참조하세요.

선택적 도구 로딩

토큰 오버헤드를 줄이기 위해 필요한 도구 그룹만 로드하세요:

langfuse-mcp --tools traces,prompts

사용 가능한 그룹: traces, observations, sessions, exceptions, prompts, datasets, annotation_queues, scores, schema

읽기 전용 모드

더 안전한 읽기 전용 액세스를 위해 모든 쓰기 작업을 비활성화하세요:

langfuse-mcp --read-only
# Or via environment variable
LANGFUSE_MCP_READ_ONLY=true langfuse-mcp

이 설정은 다음을 비활성화합니다: create_text_prompt, create_chat_prompt, update_prompt_labels, create_dataset, create_dataset_item, delete_dataset_item, create_annotation_queue, create_annotation_queue_item, update_annotation_queue_item, delete_annotation_queue_item, create_annotation_queue_assignment, delete_annotation_queue_assignment

기타 클라이언트

Cursor

프로젝트에 .cursor/mcp.json을 생성하세요 (전역 설정은 ~/.cursor/mcp.json):

{
  "mcpServers": {
    "langfuse": {
      "command": "uvx",
      "args": ["--python", "3.11", "langfuse-mcp"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-...",
        "LANGFUSE_SECRET_KEY": "sk-...",
        "LANGFUSE_HOST": "https://cloud.langfuse.com"
      }
    }
  }
}

Docker

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

개발

uv venv --python 3.11 .venv && source .venv/bin/activate
uv pip install -e ".[dev]"
pytest

라이선스

MIT

Install Server

A

security – no known vulnerabilities

A

license - permissive license

-

quality - not tested

How are these scores calculated?

Resources

GitHub Repository

Need Help?

Related Servers

Tools

View all tools

langfuse-mcp