A Model Context Protocol (MCP) server that provides AI assistants with the ability to query and analyze logs from Grafana Loki. This server enables seamless integration between AI assistants and Loki, allowing for intelligent log analysis, troubleshooting, and monitoring workflows.

┌─────────────────┐    MCP Protocol    ┌─────────────────┐    HTTP/API    ┌─────────────────┐
│   AI Assistant │ ◄─────────────────► │ Loki MCP Server │ ◄─────────────►│  Grafana Loki   │
│   (Claude et al)│                    │                 │                │   Log System    │
└─────────────────┘                    └─────────────────┘                └─────────────────┘

• 🔍 Query Logs: Execute LogQL queries against Loki with support for range and instant queries
• 🔎 Search Logs: Keyword-based log searching with advanced filtering and pattern matching
• 🏷️ Label Discovery: Retrieve available log labels and label values for stream exploration
• 🤖 MCP Protocol: Fully compatible with Model Context Protocol for AI assistant integration
• ⚡ Performance: Built-in caching and optimized query execution
• 🛡️ Security: Support for multiple authentication methods (basic auth, bearer tokens)
• 📊 Rich Results: Structured output with timestamps, labels, and context information

1. Clone the repository:

git clone <repository-url>
cd loki-mcp-server

2. Install the package:

pip install -e .

For development work, install with development dependencies:

pip install -e ".[dev]"

• Python 3.8 or higher
• Access to a Grafana Loki instance
• Network connectivity to your Loki server

Configure the server using these environment variables:

export LOKI_URL="http://localhost:3100"

export LOKI_URL="https://loki.example.com"
export LOKI_USERNAME="service-account"
export LOKI_PASSWORD="secure-password"

export LOKI_URL="https://loki.example.com"
export LOKI_BEARER_TOKEN="your-api-token"

You can also use a .env file in your project directory:

LOKI_URL=http://localhost:3100
LOKI_USERNAME=admin
LOKI_PASSWORD=password123

Start the MCP server using the command line:

loki-mcp-server

The server will start and listen for MCP protocol messages via stdio.

Add the server to your AI assistant's MCP configuration. Example for Claude Desktop:

{
  "mcpServers": {
    "loki": {
      "command": "loki-mcp-server",
      "env": {
        "LOKI_URL": "http://localhost:3100"
      }
    }
  }
}

The server provides three main tools for log analysis:

Execute LogQL queries directly against Loki.

Parameters:

• query (required): LogQL query string
• start (optional): Start time for range queries
• end (optional): End time for range queries
• limit (optional): Maximum entries to return (default: 100)
• direction (optional): Query direction ('forward' or 'backward')

Search logs using keywords with advanced filtering.

Parameters:

• keywords (required): List of keywords to search for
• labels (optional): Label filters as key-value pairs
• start (optional): Start time for search range
• end (optional): End time for search range
• limit (optional): Maximum entries to return (default: 100)
• case_sensitive (optional): Case-sensitive search (default: false)
• operator (optional): Logical operator ('AND' or 'OR')

Discover available labels and their values.

Parameters:

• label_name (optional): Specific label to get values for
• start (optional): Start time for label query
• end (optional): End time for label query
• use_cache (optional): Use cached results (default: true)

1. Clone and install:

git clone <repository-url>
cd loki-mcp-server
pip install -e ".[dev]"

2. Run tests:

pytest

3. Run specific test suites:

# Unit tests only
pytest tests/unit/

# Integration tests only  
pytest tests/integration/

# Performance tests
pytest tests/performance/

Run linting and formatting:

# Format code
black .
isort .

# Type checking
mypy app/

# Linting
ruff check .

loki-mcp-server/
├── app/          # Main package
│   ├── __init__.py
│   ├── main.py               # CLI entry point
│   ├── server.py             # MCP server implementation
│   ├── config.py             # Configuration management
│   ├── loki_client.py        # Basic Loki client
│   ├── enhanced_client.py    # Enhanced client with features
│   ├── query_builder.py      # LogQL query building
│   ├── error_handler.py      # Error classification and handling
│   ├── logging_config.py     # Logging setup
│   └── tools/                # MCP tools
│       ├── query_logs.py     # LogQL query tool
│       ├── search_logs.py    # Keyword search tool
│       └── get_labels.py     # Label discovery tool
├── tests/                    # Test suite
├── pyproject.toml           # Project configuration
└── README.md               # This file

The project includes comprehensive tests:

• Unit Tests: Test individual components in isolation
• Integration Tests: Test MCP protocol and Loki integration
• Performance Tests: Benchmark query performance
• Mock Tests: Test with simulated Loki responses

Run all tests:

pytest

Run with coverage:

pytest --cov=app --cov-report=html

• Verify LOKI_URL is correct and accessible
• Check firewall and network connectivity
• Ensure Loki is running and healthy

• Verify credentials are correct
• Check if Loki requires authentication
• Ensure bearer token is valid and not expired

• Validate LogQL syntax
• Check label names and values exist
• Verify time range is reasonable

Enable debug logging by setting:

export PYTHONPATH=.
python -m app.main --debug

1. Check the troubleshooting guide in docs/troubleshooting.md
2. Review example configurations in examples/
3. Run the test suite to verify your setup
4. Check Loki server logs for additional context

MIT License - see LICENSE file for details.