Model Context Protocol (MCP) Server

The LogChef MCP server enables AI assistants to interact with your LogChef deployment through the Model Context Protocol. This integration makes log analysis and troubleshooting accessible through natural conversation with AI assistants like Claude Desktop.

Natural Language Queries

Ask AI assistants to query your logs using plain English. No need to remember SQL syntax or field names.

Schema Discovery

AI assistants can explore your log structure and understand what data is available in your sources.

Team Management

Manage teams, users, and source access through conversational AI interaction.

Saved Query Collections

Create and organize frequently-used queries through AI assistance.

What You Can Do

With the LogChef MCP server, you can ask AI assistants to help you:

Explore your log infrastructure: See what teams you belong to and what log sources are available
Query logs effectively: Execute ClickHouse SQL queries to find specific log entries, errors, or patterns
Understand your data: Get schema information to know what fields are available in your logs
Analyze log patterns: Generate histograms and time-series data for trend analysis
Manage saved queries: Create and organize collections of frequently-used queries
Administer teams and users: Handle team membership, user management, and source configuration (admin users)

Example Conversations

Here are some examples of how you might interact with AI assistants through the MCP server:

Discovery:

“What log sources do I have access to?”

Troubleshooting:

“Find all 500 errors in the last hour from the web service logs”

Analysis:

“Show me a histogram of log volume over the past day”

Investigation:

“What are the most common error messages in the database logs?”

Query Management:

“Create a saved query for tracking API response times above 1 second”

Installation and Setup

Prerequisites

A running LogChef instance
A valid LogChef API token with appropriate permissions
An AI assistant that supports MCP (like Claude Desktop)

Generating an API Token

Log into your LogChef instance
Navigate to your profile settings
Create a new API token with the permissions you need
Copy the token for use in the MCP server configuration

Installation Options

Option 1: Docker (Recommended)

For most users, Docker provides the easiest setup:

# Pull the latest image
docker pull logchef-mcp

# For Claude Desktop integration (STDIO mode)
docker run --rm -i \
  -e LOGCHEF_URL=http://localhost:8125 \
  -e LOGCHEF_API_KEY=<your_api_token> \
  logchef-mcp -t stdio

Option 2: Binary Download

Download the latest release from the releases page and place it in your $PATH.

Option 3: Build from Source

If you have Go installed:

git clone https://github.com/mr-karan/logchef-mcp.git
cd logchef-mcp
go build -o logchef-mcp ./cmd/logchef-mcp

Claude Desktop Configuration

Add the MCP server to your Claude Desktop configuration:

Using Docker:

{
  "mcpServers": {
    "logchef": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "LOGCHEF_URL",
        "-e",
        "LOGCHEF_API_KEY",
        "logchef-mcp",
        "-t",
        "stdio"
      ],
      "env": {
        "LOGCHEF_URL": "http://localhost:8125",
        "LOGCHEF_API_KEY": "<your_api_token>"
      }
    }
  }
}

Using Binary:

{
  "mcpServers": {
    "logchef": {
      "command": "logchef-mcp",
      "args": [],
      "env": {
        "LOGCHEF_URL": "http://localhost:8125",
        "LOGCHEF_API_KEY": "<your_api_token>"
      }
    }
  }
}

Available Tools

The MCP server provides tools organized into categories that can be selectively enabled:

Profile & Metadata

get_profile - Get current user information
get_teams - List user’s team memberships
get_meta - Get server version and metadata

Source Management

get_sources - List all accessible log sources
get_team_sources - List sources for a specific team

Log Analysis

query_logs - Execute ClickHouse SQL queries
get_source_schema - Get table schema information
get_log_histogram - Generate histogram data
get_collections - List saved query collections
create_collection - Create new saved queries
update_collection - Modify existing collections
delete_collection - Remove saved queries

Administration (Admin Users Only)

Team management (create, update, delete teams)
User management (create, update, delete users)
Source management (create, validate, delete sources)
API token management

Transport Modes

The MCP server supports multiple transport modes:

STDIO Mode (Default)

Direct integration with AI assistants like Claude Desktop:

logchef-mcp -t stdio

Server-Sent Events (SSE)

Run as HTTP server for web-based clients:

logchef-mcp -t sse

Streamable HTTP

Independent server for multiple client connections:

logchef-mcp -t streamable-http

Tool Configuration

You can selectively enable tool categories:

# Enable only profile and log analysis tools
logchef-mcp --enabled-tools "profile,logs"

# Disable admin tools
logchef-mcp --disable-admin

Available categories: profile, sources, logs, admin

Authentication Options

Environment Variables

export LOGCHEF_URL=http://localhost:8125
export LOGCHEF_API_KEY=your_token_here

HTTP Headers (SSE/HTTP modes)

For server modes, credentials can be passed via headers:

X-Logchef-URL: LogChef instance URL
X-Logchef-API-Key: API token

Debug Mode

Enable detailed logging for troubleshooting:

logchef-mcp -debug

This provides HTTP request/response logging between the MCP server and LogChef API.

Working with AI Assistants

The MCP server enables powerful natural language interactions:

Discovery Workflow

“What log sources do I have access to?” → AI uses get_sources
“What data is in the nginx source?” → AI calls get_source_schema
“Show me recent errors” → AI constructs and executes ClickHouse queries

Practical Examples

Troubleshooting:

“Find all 500 errors in the last hour from the web service logs”

Analysis:

“Show me a histogram of log volume over the past day grouped by service”

Investigation:

“What are the most common error messages in logs containing ‘database’?”

Monitoring:

“Create a saved query for tracking API response times above 2 seconds”

AI-Assisted Query Building

The AI assistant understands ClickHouse SQL and can help you:

Build complex queries with proper syntax
Optimize queries for better performance
Explain available fields in your log data
Suggest useful queries based on common log analysis patterns

Since LogChef uses ClickHouse as the storage backend, you get the full power of ClickHouse’s analytical capabilities through natural language interaction.

Security Considerations

API Token Scope: Create API tokens with minimal required permissions
Network Access: Ensure the MCP server can reach your LogChef instance
Tool Categories: Disable admin tools if not needed to reduce attack surface
Environment Variables: Store sensitive credentials securely

Troubleshooting

Common Issues

Connection Errors:

Verify LOGCHEF_URL is correct and accessible
Check API token permissions
Ensure LogChef instance is running

Permission Errors:

Verify API token has required permissions
Check team membership for source access
Confirm admin status for administrative operations

Tool Availability:

Check enabled tool categories
Verify LogChef version compatibility
Review API token scope

Debug Output

Use debug mode to see detailed HTTP interactions:

logchef-mcp -debug -t stdio

Repository and Development

The LogChef MCP server is open source and available at: https://github.com/mr-karan/logchef-mcp

Contributions are welcome! The project includes:

Comprehensive tool coverage of LogChef APIs
Multiple transport mode support
Flexible authentication options
Production-ready Docker images

For development setup and contribution guidelines, see the repository documentation.