Simple Loki MCP

What is Simple Loki MCP Server?

Simple Loki MCP Server is a Model Context Protocol (MCP) interface designed to allow AI assistants to query and analyze logs stored in Grafana Loki. It acts as a bridge between AI models and Loki, enabling seamless access to log data for various analytical tasks.

How to use Simple Loki MCP Server?

Installation:

Via Smithery: npx -y @smithery/cli install @ghrud92/simple-loki-mcp --client claude
For MCP: Configure your mcpServers with the provided JSON snippet.
NPM: Clone the repository, install dependencies (npm install), and build the project (npm run build).

Starting the Server:

npm start (for production)
npm run dev (for development)

Configuration:

Environment Variables: Set LOKI_ADDR, LOKI_USERNAME, LOKI_PASSWORD, etc., for Loki access.
Config Files: Create a logcli-config.yaml in specified locations with Loki connection details.

Available MCP Tools:

query-loki: Query logs using LogQL with various filtering options.
get-label-values: Retrieve all values for a specific label.
get-labels: Retrieve all available labels.

Key Features of Simple Loki MCP Server

LogQL Support: Full support for querying Loki logs using LogQL.
Metadata Retrieval: Ability to get label values and other metadata.
Flexible Authentication: Supports authentication and configuration via environment variables or config files.
Multiple Output Formats: Provides results in default, raw, or JSON lines formats.
Automatic Fallback: Seamlessly switches to Loki HTTP API if logcli is not available.
Node.js & TypeScript: Built with modern web technologies.

Use Cases of Simple Loki MCP Server

AI-powered Log Analysis: Enable AI assistants to directly query and analyze log data for anomaly detection, troubleshooting, and performance monitoring.
Automated Incident Response: Integrate with AI systems to automatically fetch relevant logs during incidents.
Proactive Monitoring: Allow AI models to continuously monitor logs for specific patterns or events.
Customizable Dashboards: Feed log data to custom dashboards or reporting tools.

FAQ about Simple Loki MCP Server

Q: What are the prerequisites for running Simple Loki MCP Server? A: Node.js v16 or higher, TypeScript, and optionally Grafana Loki logcli installed and accessible in your PATH. Access to a Loki server instance is also required.

Q: What happens if logcli is not installed? A: The server will automatically fall back to using the Loki HTTP API. No additional configuration is needed, and the same authentication parameters are used.

Q: How can I configure Loki access? A: You can configure Loki access using environment variables (e.g., LOKI_ADDR, LOKI_USERNAME) or by creating a logcli-config.yaml file.

Q: What output formats are supported for queries? A: You can get results in "default", "raw", or "jsonl" (JSON lines) formats.

Q: Can I use this with Claude Desktop? A: Yes, you can install it for Claude Desktop automatically via Smithery.

Simple Loki MCP Server

Loki MCP Server is a Model Context Protocol (MCP) interface for querying Grafana Loki logs using logcli. The server enables AI assistants to access and analyze log data from Loki directly.

Features

Query Loki logs with full LogQL support
Get label values and metadata
Authentication and configuration support via environment variables or config files
Provides formatted results in different output formats (default, raw, JSON lines)
Automatic fallback to HTTP API when logcli is not available in the environment

Prerequisites

Node.js v16 or higher
TypeScript
(Optional) Grafana Loki logcli installed and accessible in your PATH. If logcli is not available, the server will automatically use the Loki HTTP API instead
Access to a Loki server instance

Installation

Installing via Smithery

To install Simple Loki MCP Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @ghrud92/simple-loki-mcp --client claude

for MCP

{
  "mcpServers": {
    "simple-loki": {
      "command": "npx",
      "args": ["-y", "simple-loki-mcp"],
      "env": {
        "LOKI_ADDR": "https://loki.sup.band"
      }
    }
  }
}

npm

Clone the repository:

git clone https://github.com/ghrud92/loki-mcp.git
cd loki-mcp

Install dependencies:

npm install

Build the project:

npm run build

Available MCP Tools

query-loki

Query logs from Loki with filtering options.

Parameters:

query (required): Loki query string (LogQL)
from: Start timestamp (e.g. "2023-01-01T12:00:00Z")
to: End timestamp (e.g. "2023-01-01T13:00:00Z")
limit: Maximum number of logs to return
batch: Batch size for query results
output: Output format ("default", "raw", or "jsonl")
quiet: Suppress query metadata
forward: Display results in chronological order

get-label-values

Retrieve all values for a specific label.

Parameters:

label (required): Label name to get values for

get-labels

Retrieve all available labels.

No parameters required.

Configuration

You can configure Loki access using:

Environment Variables

LOKI_ADDR: Loki server address (URL)
LOKI_USERNAME: Username for basic auth
LOKI_PASSWORD: Password for basic auth
LOKI_TENANT_ID: Tenant ID for multi-tenant Loki
LOKI_BEARER_TOKEN: Bearer token for authentication
LOKI_BEARER_TOKEN_FILE: File containing bearer token
LOKI_CA_FILE: Custom CA file for TLS
LOKI_CERT_FILE: Client certificate file for TLS
LOKI_KEY_FILE: Client key file for TLS
LOKI_ORG_ID: Organization ID for multi-org setups
LOKI_TLS_SKIP_VERIFY: Skip TLS verification ("true" or "false")
LOKI_CONFIG_PATH: Custom path to config file
DEBUG: Enable debug logging

Note: When the client is using the HTTP API mode (when logcli is not available), the same configuration parameters are used to authenticate and connect to the Loki server.

Config Files

Alternatively, create a logcli-config.yaml file in one of these locations:

Custom path specified by LOKI_CONFIG_PATH
Current working directory
Your home directory (~/.logcli-config.yaml)

Example config file:

addr: https://loki.example.com
username: user
password: pass
tenant_id: mytenant

Usage

Start the server:

npm start

For development:

npm run dev

Implementation Details

Automatic Fallback to HTTP API

The server will automatically check if logcli is installed and available in the environment:

If logcli is available, it will be used for all queries, providing the full functionality of the CLI tool
If logcli is not available, the server will automatically fall back to using the Loki HTTP API:
- No additional configuration is needed
- The same authentication parameters are used for the HTTP API
- Response formatting is consistent with the CLI output
- Default limit of 1000 logs per query is applied in both modes

This automatic detection ensures that the server works seamlessly in different environments without manual configuration.

Development

# Run linter
npm run lint

# Fix linting issues
npm run lint:fix

# Run tests
npm run test

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

Simple Loki MCP Overview