📌Overview

Purpose: The Logfire MCP server enables seamless access and analysis of OpenTelemetry traces and metrics for applications using Logfire.

Overview: This server provides a robust Model Context Protocol (MCP) environment, allowing large language models (LLMs) to retrieve application telemetry data, analyze distributed traces, and execute SQL queries through Logfire APIs.

Key Features:

Find Exceptions: This tool retrieves exception counts from traces, grouped by file, allowing quick identification of potential issues in the codebase.
Find Exceptions in File: This feature provides detailed information about exceptions that occurred in a specific file, helping developers to diagnose issues quickly and precisely.
Arbitrary Query: Users can run custom SQL queries on their OpenTelemetry traces and metrics, offering flexibility to extract specific insights tailored to their needs.
Schema Retrieval: Offers an endpoint to fetch the OpenTelemetry schema, aiding developers in creating effective custom queries.

Logfire MCP Server

This repository contains a Model Context Protocol (MCP) server that enables LLMs to access OpenTelemetry traces and metrics sent to Logfire. It allows retrieval of telemetry data, analysis of distributed traces, and execution of arbitrary SQL queries via the Logfire APIs.

Available Tools

find_exceptions: Get exception counts from traces grouped by file.
- Required arguments:
  - age (int): Number of minutes to look back (e.g., 30 for last 30 minutes, max 7 days).
find_exceptions_in_file: Get detailed trace information about exceptions in a specific file.
- Required arguments:
  - filepath (string): Path to the file to analyze.
  - age (int): Number of minutes to look back (max 7 days).
arbitrary_query: Run custom SQL queries on your OpenTelemetry traces and metrics.
- Required arguments:
  - query (string): SQL query to execute.
  - age (int): Number of minutes to look back (max 7 days).
get_logfire_records_schema: Get the OpenTelemetry schema for custom queries.
- No required arguments.

Setup

Install `uv`

Ensure uv is installed to run the MCP server. For installation instructions, refer to the uv installation docs. If you have an older version of uv, update it with uv self update.

Obtain a Logfire Read Token

To make requests to the Logfire APIs, create a "read token" in the "Read Tokens" section of your project settings in Logfire: Logfire Read Tokens.

Important: Logfire read tokens are project-specific, so create one for the specific project.

Manually Run the Server

With uv installed and a Logfire read token, manually run the MCP server using uvx. Specify your read token with the LOGFIRE_READ_TOKEN environment variable or --read-token flag:

LOGFIRE_READ_TOKEN=YOUR_READ_TOKEN uvx logfire-mcp

uvx logfire-mcp --read-token=YOUR_READ_TOKEN

Note: If using MCP clients like Cursor, Claude Desktop, or Cline, you do not need to manually run the server. Refer to the next section for configuration details.

Configuration with MCP Clients

Configure for Cursor

Create a .cursor/mcp.json file in your project root:

{
  "mcpServers": {
    "logfire": {
      "command": "uvx",
      "args": ["logfire-mcp", "--read-token=YOUR-TOKEN"]
    }
  }
}

Configure for Claude Desktop

Add to your Claude settings:

{
  "command": ["uvx"],
  "args": ["logfire-mcp"],
  "type": "stdio",
  "env": {
    "LOGFIRE_READ_TOKEN": "YOUR_TOKEN"
  }
}

Configure for Cline

Add to cline_mcp_settings.json:

{
  "mcpServers": {
    "logfire": {
      "command": "uvx",
      "args": ["logfire-mcp"],
      "env": {
        "LOGFIRE_READ_TOKEN": "YOUR_TOKEN"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Customization - Base URL

The server connects to the Logfire API at https://logfire-api.pydantic.dev by default. Override this by using the --base-url argument or setting the environment variable LOGFIRE_BASE_URL:

uvx logfire-mcp --base-url=https://your-logfire-instance.com

LOGFIRE_BASE_URL=https://your-logfire-instance.com uvx logfire-mcp

Example Interactions

Find all exceptions in traces from the last hour:

{
  "name": "find_exceptions",
  "arguments": {
    "age": 60
  }
}

Get details about exceptions from a specific file:

{
  "name": "find_exceptions_in_file",
  "arguments": {
    "filepath": "app/api.py",
    "age": 1440
  }
}

Run a custom query on traces:

{
  "name": "arbitrary_query",
  "arguments": {
    "query": "SELECT trace_id, message, created_at, attributes->>'service.name' as service FROM records WHERE severity_text = 'ERROR' ORDER BY created_at DESC LIMIT 10",
    "age": 1440
  }
}

Examples of Questions for Claude

"What exceptions occurred in traces from the last hour across all services?"
"Show me the recent errors in the file 'app/api.py' with their trace context."
"How many errors were there in the last 24 hours per service?"
"What are the most common exception types in my traces, grouped by service name?"
"Get me the OpenTelemetry schema for traces and metrics."
"Find all errors from yesterday and show their trace contexts."

Getting Started

Obtain a Logfire read token from: Logfire Read Tokens.

Run the MCP server:

uvx logfire-mcp --read-token=YOUR_TOKEN

Configure your client (Cursor, Claude Desktop, or Cline) using the above examples.
Start using the MCP server to analyze your OpenTelemetry traces and metrics!

Contributing

Contributions are welcome to improve the Logfire MCP server, whether by adding new trace analysis tools, enhancing querying functionality, or improving documentation.

License

Logfire MCP is licensed under the MIT License, allowing for free use, modification, and distribution.

logfire-mcp