LogMCP Server

A Model Context Protocol (MCP) server implementation for log querying and system monitoring via Loki, using stdio transport.

Features

• MCP Protocol Support: Full implementation of the Model Context Protocol using stdio transport
• Loki Integration: Query logs from Loki using LogQL
• Multiple Environments: Support for test, dev, and prod environments
• Flexible Queries: Keyword-based and time-range-based log queries
• Error Handling: Comprehensive error handling and logging
• Async Support: Fully asynchronous implementation

Installation

This project uses uv as the package manager.

Prerequisites

• Python 3.8+
• uv package manager

Install uv

# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Install Dependencies

# Install project dependencies
uv sync

# Install development dependencies
uv sync --dev

Configuration

The server can be configured using environment variables:

SSL Configuration

For test environments with self-signed certificates, you can disable SSL certificate verification:

# Disable SSL verification (for test environments only)
export LOKI_SSL_VERIFY=false

# Or enable SSL verification (default, recommended for production)
export LOKI_SSL_VERIFY=true

Security Note: Only disable SSL verification in test environments. Always keep SSL verification enabled in production environments for security.

Usage

Running the Server

# Using uvx
uvx logmcp

# Or using uv
uv run python main.py

# Or directly with Python
python main.py

MCP Tools

The server provides two main MCP tools:

1. loki_keyword_query

Query logs containing keywords from the last 30 days.

Parameters:

• env (required): Environment name (test, dev, prod)
• keywords (required): Search keywords (comma-separated)
• service_name (optional): Service name (default: zkme-token)
• namespace (optional): Loki namespace (auto-detected from env)
• limit (optional): Result limit (default: 1000)

2. loki_range_query

Query logs containing keywords within a specified time range.

Parameters:

• env (required): Environment name (test, dev, prod)
• start_date (required): Start date (YYYYMMDD format)
• end_date (required): End date (YYYYMMDD format)
• keywords (required): Search keywords (comma-separated)
• service_name (optional): Service name (default: zkme-token)
• namespace (optional): Loki namespace (auto-detected from env)
• limit (optional): Result limit (default: 1000)

Development

Running Tests

# Run all tests
uvx pytest

# Run tests with coverage
uvx pytest --cov=src/logmcp

# Run specific test file
uvx pytest tests/test_server.py

Code Formatting

# Format code with black
uvx black src tests

# Sort imports with isort
uvx isort src tests

# Type checking with mypy
uvx mypy src

Project Structure

LogMCP/
├── pyproject.toml              # uv project configuration
├── main.py                     # Program entry point
├── README.md                   # Project documentation
├── src/logmcp/
│   ├── __init__.py            # Package initialization
│   ├── server.py              # MCP server implementation
│   ├── tools.py               # MCP tools implementation
│   ├── config.py              # Configuration management
│   ├── logger.py              # Logging utilities
│   └── services/
│       ├── __init__.py        # Services package
│       └── loki_service.py    # Loki integration service
└── tests/
    ├── __init__.py            # Test package
    ├── test_server.py         # Server tests
    ├── test_tools.py          # Tools tests
    └── test_loki_service.py   # Loki service tests

License

This project is licensed under the MIT License.