📌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 with tools to access the OpenTelemetry traces and metrics sent to Logfire.

The MCP server enables LLMs to retrieve your application's telemetry data, analyze distributed traces, and utilize the results of SQL queries executed using 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 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 to assist with custom queries
No required arguments

Setup

Install `uv`

Make sure uv is installed, as it is used to run the MCP server.

Installation instructions are available in the uv installation docs.

If you have an older version of uv, update it with:

uv self update

Obtain a Logfire Read Token

A "read token" is required to make requests to the Logfire APIs.

Create one in the "Read Tokens" section of your project settings in Logfire:

https://logfire.pydantic.dev/-/redirect/latest-project/settings/read-tokens

Note: Read tokens are project-specific. Create one for the project you want to expose to the MCP server.

Run the Server Manually

With uv installed and a Logfire read token, run the MCP server using uvx:

Using environment variable:

LOGFIRE_READ_TOKEN=YOUR_READ_TOKEN uvx logfire-mcp

Using command line flag:

uvx logfire-mcp --read-token=YOUR_READ_TOKEN

If using MCP clients like Cursor, Claude Desktop, or Cline that manage MCP servers, manual running is not needed.

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"]
    }
  }
}

Cursor requires the --read-token flag since it doesn’t accept the env field.

Configure for Claude Desktop

Add the following 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

By default, the server connects to https://logfire-api.pydantic.dev. Override with:

Command line argument:

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

Environment variable:

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
  }
}

Response:

[
  {
    "filepath": "app/api.py",
    "count": 12
  },
  {
    "filepath": "app/models.py",
    "count": 5
  }
]

Get details about exceptions from traces in a specific file:

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

Response:

[
  {
    "created_at": "2024-03-20T10:30:00Z",
    "message": "Failed to process request",
    "exception_type": "ValueError",
    "exception_message": "Invalid input format",
    "function_name": "process_request",
    "line_number": "42",
    "attributes": {
      "service.name": "api-service",
      "code.filepath": "app/api.py"
    },
    "trace_id": "1234567890abcdef"
  }
]

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
  }
}

Example Questions for Claude

What exceptions occurred in traces from the last hour across all services?
Show me 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:
https://logfire.pydantic.dev/-/redirect/latest-project/settings/read-tokens

Run the MCP server:

uvx logfire-mcp --read-token=YOUR_TOKEN

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

Contributing

Contributions to improve the Logfire MCP server are welcome. You can add new trace analysis tools, enhance metrics querying, or improve documentation.

For examples of MCP servers and implementation patterns, see the Model Context Protocol servers repository.

License

Logfire MCP is licensed under the MIT License, allowing free use, modification, and distribution subject to the license terms.

logfire-mcp