Simple Loki MCP Server for logcli Queries

Overview

This MCP (Model Context Protocol) server provides a minimal HTTP wrapper around logcli to query Grafana Loki. It exposes a lightweight MCP-compatible endpoint that runs logcli under the hood and returns logs as JSON or plain text. The goal is to offer a fast, dependency-light way for developer tools, automation, or LLMs to fetch contextual log data without embedding Loki client libraries.

Because it uses logcli (the official Loki CLI), you get the same query syntax and authentication options you’re used to while keeping the server footprint small. It is particularly useful when you want a simple HTTP tool that translates MCP-style requests into Loki queries, suitable for integrating into chatops, incident responders, or AI agents that need on-demand log access.

Features

• Uses logcli to execute Loki queries, so no additional Loki client code required
• Exposes a simple MCP-compatible HTTP API for querying logs
• Supports common query parameters: PromQL-like Loki queries, time ranges, limit, direction
• Returns structured JSON (timestamp + line) or raw output
• Easy to run locally or in Docker, configurable via environment variables
• Lightweight and intended for quick integration with automation or AI tools

Installation / Configuration

Prerequisites:

• logcli installed and accessible in the container/host
• Network access to your Loki instance

Clone and build (example using Go or a simple run script — replace with build steps appropriate for the repo):

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

# If the repo includes a Go server
go build -o simple-loki-mcp ./cmd/server

Run locally (example):

# Configure environment variables and run the binary
export LOKI_URL="https://loki.example.com"
export LOGCLI_PATH="/usr/local/bin/logcli"
export PORT=8080

./simple-loki-mcp

Docker (build and run):

# Build the image
docker build -t simple-loki-mcp .

# Run the container
docker run -e LOKI_URL="https://loki.example.com" \
           -e LOGCLI_PATH="/usr/bin/logcli" \
           -e PORT=8080 \
           -p 8080:8080 \
           simple-loki-mcp

Example configuration file (optional JSON config):

{
  "port": 8080,
  "logcli_path": "/usr/local/bin/logcli",
  "loki_url": "https://loki.example.com",
  "default_limit": 100
}

Environment variables reference:

Available Tools / Resources

• logcli (Loki CLI): https://grafana.com/docs/loki/latest/getting-started/logcli/
• Grafana Loki docs: https://grafana.com/docs/loki/latest/
• MCP (Model Context Protocol) concepts: use HTTP POST to send tool-like requests from AI agents (see your agent framework docs)

API / Example Requests

Basic POST to query logs (JSON):

Request:

POST /mcp/query HTTP/1.1
Content-Type: application/json

{
  "query": "{app=\"my-app\"} |= \"error\"",
  "limit": 50,
  "start": "2026-04-10T10:00:00Z",
  "end": "2026-04-10T10:15:00Z",
  "format": "json"
}

Example response (JSON):

{
  "status": "success",
  "query": "{app=\"my-app\"} |= \"error\"",
  "results": [
    {"ts":"2026-04-10T10:02:34Z","line":"2026-04-10T10:02:34Z error something failed in service X"},
    {"ts":"2026-04-10T10:03:01Z","line":"2026-04-10T10:03:01Z error connection timed out"}
  ]
}

You can also request raw output:

POST /mcp/query
Content-Type: application/json

{
  "query":"{job=\"backend\"}",
  "format":"raw",
  "limit": 20
}

Use Cases

• Debugging from chatbots: Attach this MCP server to an LLM-based assistant so it can fetch recent error logs given a natural language signal (e.g., “show me errors for service X in the last 10 minutes”).
  • Agent sends an MCP POST with the appropriate Loki query and time range, receives structured logs for summarization.
• Incident enrichment for alerts: A webhook receiver can call the MCP endpoint to include a short, contextual log excerpt in PagerDuty/SMS/Slack notifications.
  • Example: on alert, call /mcp/query with the alert’s labels to append the