https://github.com/avivsinai/langfuse-mcp
A Model Context Protocol (MCP) server for Langfuse, enabling AI agents to query Langfuse trace data for enhanced debugging and observability
https://github.com/avivsinai/langfuse-mcp
genai langfuse mcp mcp-server
Last synced: 7 months ago
JSON representation
A Model Context Protocol (MCP) server for Langfuse, enabling AI agents to query Langfuse trace data for enhanced debugging and observability
- Host: GitHub
- URL: https://github.com/avivsinai/langfuse-mcp
- Owner: avivsinai
- License: mit
- Created: 2025-03-21T06:44:44.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-01-13T11:49:59.000Z (7 months ago)
- Last Synced: 2026-01-16T18:13:02.105Z (7 months ago)
- Topics: genai, langfuse, mcp, mcp-server
- Language: Python
- Homepage:
- Size: 190 KB
- Stars: 34
- Watchers: 1
- Forks: 12
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
- awesome-mcp-servers - **langfuse-mcp** - A Model Context Protocol (MCP) server for Langfuse, enabling AI agents to query Langfuse trace data for enhanced debugging and observability `python` `genai` `langfuse` `mcp` `mcp-server` `pip install git+https://github.com/avivsinai/langfuse-mcp` (🤖 AI/ML)
- awesome-mcp-security - langfuse-mcp - mcp) | (📊 Monitoring (16 servers))
README
# Langfuse MCP Server
[](https://badge.fury.io/py/langfuse-mcp)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[Model Context Protocol](https://modelcontextprotocol.io) server for [Langfuse](https://langfuse.com) observability. Query traces, debug errors, analyze sessions, manage prompts.
## Why langfuse-mcp?
Comparison with [official Langfuse MCP](https://github.com/langfuse/mcp-server-langfuse) (as of Jan 2026):
| | langfuse-mcp | Official |
|-|--------------|----------|
| **Traces & Observations** | Yes | No |
| **Sessions & Users** | Yes | No |
| **Exception Tracking** | Yes | No |
| **Prompt Management** | Yes | Yes |
| **Selective Tool Loading** | Yes | No |
This project provides a **full observability toolkit** — traces, observations, sessions, exceptions, and prompts — while the official MCP focuses on prompt management.
## Quick Start
Requires [uv](https://docs.astral.sh/uv/getting-started/installation/) (for `uvx`).
Get credentials from [Langfuse Cloud](https://cloud.langfuse.com) → Settings → API Keys. If self-hosted, use your instance URL for `LANGFUSE_HOST`.
```bash
# Claude Code (project-scoped, shared via .mcp.json)
claude mcp add \
--scope project \
--env LANGFUSE_PUBLIC_KEY=pk-... \
--env LANGFUSE_SECRET_KEY=sk-... \
--env LANGFUSE_HOST=https://cloud.langfuse.com \
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
```
Restart your CLI, then verify with `/mcp` (Claude Code) or `codex mcp list` (Codex).
## Tools (18 total)
| Category | Tools |
|----------|-------|
| Traces | `fetch_traces`, `fetch_trace` |
| Observations | `fetch_observations`, `fetch_observation` |
| Sessions | `fetch_sessions`, `get_session_details`, `get_user_sessions` |
| Exceptions | `find_exceptions`, `find_exceptions_in_file`, `get_exception_details`, `get_error_count` |
| Prompts | `list_prompts`, `get_prompt`, `get_prompt_unresolved`, `create_text_prompt`, `create_chat_prompt`, `update_prompt_labels` |
| Schema | `get_data_schema` |
## Skill
This project includes a skill with debugging playbooks.
**Claude Code:**
```
/plugin marketplace add avivsinai/skills-marketplace
/plugin install langfuse@avivsinai-marketplace
```
**Codex CLI:**
```
$skill-installer install https://github.com/avivsinai/langfuse-mcp/tree/main/skills/langfuse
```
Then restart Codex.
**Manual install** (both):
```bash
cp -r skills/langfuse ~/.claude/skills/ # Claude Code
cp -r skills/langfuse ~/.codex/skills/ # Codex CLI
```
Try asking: "help me debug langfuse traces"
See [`skills/langfuse/SKILL.md`](skills/langfuse/SKILL.md) for full documentation.
## Selective Tool Loading
Load only the tool groups you need to reduce token overhead:
```bash
langfuse-mcp --tools traces,prompts
```
Available groups: `traces`, `observations`, `sessions`, `exceptions`, `prompts`, `schema`
## Other Clients
### Cursor
Create `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for global):
```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
```bash
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
```
## Development
```bash
uv venv --python 3.11 .venv && source .venv/bin/activate
uv pip install -e ".[dev]"
pytest
```
## License
MIT