grafana-loki-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a FastMCP server that allows querying Loki logs from Grafana through the Model Context Protocol (MCP). The server provides tools to query logs, get label information, and format results for Grafana/Loki log analysis.

Development Commands

Setup and Installation

# Install dependencies using uv (preferred package manager)
uv pip install -e ".[dev]"

# Install uv if not available
pip install uv

Testing

# Run all tests
pytest

# Run tests with coverage
pytest --cov=. --cov-report=term

# Run specific test files
pytest tests/test_server.py
pytest tests/test_parse_grafana_time.py

Code Quality and Linting

# Run ruff linter
ruff check .

# Run black formatter
black .

# Run type checking
mypy .

Running the Server

# Development mode with environment variables
export GRAFANA_URL=https://your-grafana-instance.com
export GRAFANA_API_KEY=your-api-key
python -m grafana_loki_mcp

# With command line arguments
python -m grafana_loki_mcp -u https://your-grafana-instance.com -k your-api-key

# Using uvx (for production)
uvx grafana-loki-mcp -u GRAFANA_URL -k GRAFANA_API_KEY

Architecture

Core Components

1. GrafanaClient (grafana_loki_mcp/server.py): Main client class that handles communication with Grafana API

   • Manages Loki datasource discovery and proxying
   • Handles time format conversion (ISO8601, Unix timestamps, Grafana relative times)
   • Provides error handling with detailed error messages

2. FastMCP Server (grafana_loki_mcp/server.py): MCP server implementation using FastMCP framework

   • Exposes tools for querying Loki logs, getting labels, and formatting results
   • Handles dynamic tool description updates with available labels
   • Supports both stdio and SSE transport protocols

3. Time Parsing (parse_grafana_time function): Handles multiple time formats

   • Grafana relative times (e.g., 'now-1h', 'now')
   • ISO8601 format
   • Unix timestamps
   • RFC3339 format