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: about 2 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 (8 months ago)
- Default Branch: main
- Last Pushed: 2025-08-09T16:56:44.000Z (3 months ago)
- Last Synced: 2025-09-07T05:54:37.948Z (about 2 months ago)
- Topics: genai, langfuse, mcp, mcp-server
- Language: Python
- Homepage:
- Size: 211 KB
- Stars: 9
- Watchers: 1
- Forks: 2
- Open Issues: 1
-
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-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)
README
# Langfuse MCP (Model Context Protocol)
[](https://github.com/avivsinai/langfuse-mcp/actions/workflows/test.yml)
[](https://badge.fury.io/py/langfuse-mcp)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
This project provides a Model Context Protocol (MCP) server for Langfuse, allowing AI agents to query Langfuse trace data for better debugging and observability.
## Quick Start with Cursor
### Installation Options
🎯 **From Cursor IDE**: Click the button above (works seamlessly!)
🌐 **From GitHub Web**: Copy this deeplink and paste into your browser address bar:
```
cursor://anysphere.cursor-deeplink/mcp/install?name=langfuse-mcp&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJsYW5nZnVzZS1tY3AiLCItLXB1YmxpYy1rZXkiLCJZT1VSX1BVQkxJQ19LRVkiLCItLXNlY3JldC1rZXkiLCJZT1VSX1NFQ1JFVF9LRVkiLCItLWhvc3QiLCJodHRwczovL2Nsb3VkLmxhbmdmdXNlLmNvbSJdfQ==
```
⚙️ **Manual Setup**: See [Configuration](#configuration-with-mcp-clients) section below
> **💡 Note**: The "Add to Cursor" button only works from within Cursor IDE due to browser security restrictions on custom protocols (`cursor://`). This is normal and expected behavior per [Cursor's documentation](https://docs.cursor.com/deeplinks).
**After installation**: Replace `YOUR_PUBLIC_KEY` and `YOUR_SECRET_KEY` with your actual Langfuse credentials in Cursor's MCP settings.
## Features
- Integration with Langfuse for trace and observation data
- Tool suite for AI agents to query trace data
- Exception and error tracking capabilities
- Session and user activity monitoring
## Available Tools
The MCP server provides the following tools for AI agents:
- `fetch_traces` - Find traces based on criteria like user ID, session ID, etc.
- `fetch_trace` - Get a specific trace by ID
- `fetch_observations` - Get observations filtered by type
- `fetch_observation` - Get a specific observation by ID
- `fetch_sessions` - List sessions in the current project
- `get_session_details` - Get detailed information about a session
- `get_user_sessions` - Get all sessions for a user
- `find_exceptions` - Find exceptions and errors in traces
- `find_exceptions_in_file` - Find exceptions in a specific file
- `get_exception_details` - Get detailed information about an exception
- `get_error_count` - Get the count of errors
- `get_data_schema` - Get schema information for the data structures
## Setup
### Install `uv`
First, make sure `uv` is installed. For installation instructions, see the [`uv` installation docs](https://docs.astral.sh/uv/getting-started/installation/).
If you already have an older version of `uv` installed, you might need to update it with `uv self update`.
### Installation
```bash
uv pip install langfuse-mcp
```
### Obtain Langfuse credentials
You'll need your Langfuse credentials:
- Public key
- Secret key
- Host URL (usually https://cloud.langfuse.com or your self-hosted URL)
## Running the Server
Run the server using `uvx`:
```bash
uvx langfuse-mcp --public-key YOUR_KEY --secret-key YOUR_SECRET --host https://cloud.langfuse.com
```
## Configuration with MCP clients
### Configure for Cursor
Create a `.cursor/mcp.json` file in your project root:
```json
{
"mcpServers": {
"langfuse": {
"command": "uvx",
"args": ["langfuse-mcp", "--public-key", "YOUR_KEY", "--secret-key", "YOUR_SECRET", "--host", "https://cloud.langfuse.com"]
}
}
}
```
### Configure for Claude Desktop
Add to your Claude settings:
```json
{
"command": ["uvx"],
"args": ["langfuse-mcp"],
"type": "stdio",
"env": {
"LANGFUSE_PUBLIC_KEY": "YOUR_KEY",
"LANGFUSE_SECRET_KEY": "YOUR_SECRET",
"LANGFUSE_HOST": "https://cloud.langfuse.com"
}
}
```
## Output Modes
Each tool supports different output modes to control the level of detail in responses:
- `compact` (default): Returns a summary with large values truncated
- `full_json_string`: Returns the complete data as a JSON string
- `full_json_file`: Saves the complete data to a file and returns a summary with file information
## Development
### Clone the repository
```bash
git clone https://github.com/yourusername/langfuse-mcp.git
cd langfuse-mcp
```
### Create a virtual environment and install dependencies
```bash
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"
```
### Set up environment variables
```bash
export LANGFUSE_SECRET_KEY="your-secret-key"
export LANGFUSE_PUBLIC_KEY="your-public-key"
export LANGFUSE_HOST="https://cloud.langfuse.com" # Or your self-hosted URL
```
### Testing
To run the demo client:
```bash
uv run examples/langfuse_client_demo.py --public-key YOUR_PUBLIC_KEY --secret-key YOUR_SECRET_KEY
```
Or use the convenience wrapper:
```bash
uv run run_mcp.py
```
## Version Management
This project uses dynamic versioning based on Git tags:
1. The version is automatically determined from git tags using `uv-dynamic-versioning`
2. To create a new release:
- Tag your commit with `git tag v0.1.2` (following semantic versioning)
- Push the tag with `git push --tags`
- Create a GitHub release from the tag
3. The GitHub workflow will automatically build and publish the package with the correct version to PyPI
For a detailed history of changes, please see the [CHANGELOG.md](CHANGELOG.md) file.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Cache Management
We use the `cachetools` library to implement efficient caching with proper size limits:
- Uses `cachetools.LRUCache` for better reliability
- Configurable cache size via the `CACHE_SIZE` constant
- Automatically evicts the least recently used items when caches exceed their size limits