MCP Server

The Logchef MCP server lets AI assistants query logs, explore schemas, manage alerts, and administer your Logchef deployment through the Model Context Protocol. It exposes 37 tools across 10 categories, plus resources and guided investigation prompts.

Prerequisites

Before configuring your client, you need:

A running Logchef instance — the MCP server connects to Logchef’s HTTP API.
An API token — generate one from your Logchef profile settings page. The token determines what data the MCP server can access.

Quick Start

Pick your client and follow the setup instructions.

claude mcp add logchef -- logchef-mcp

Set the required environment variables before launching Claude Code:

export LOGCHEF_URL=https://your-logchef-instance.com
export LOGCHEF_API_KEY=your_api_token

Or pass them inline:

LOGCHEF_URL=https://your-logchef-instance.com \
LOGCHEF_API_KEY=your_api_token \
claude

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "logchef": {
      "command": "logchef-mcp",
      "args": [],
      "env": {
        "LOGCHEF_URL": "https://your-logchef-instance.com",
        "LOGCHEF_API_KEY": "your_api_token"
      }
    }
  }
}

Add to your Cursor MCP configuration (.cursor/mcp.json):

{
  "mcpServers": {
    "logchef": {
      "command": "logchef-mcp",
      "args": [],
      "env": {
        "LOGCHEF_URL": "https://your-logchef-instance.com",
        "LOGCHEF_API_KEY": "your_api_token"
      }
    }
  }
}

Add to .vscode/settings.json:

{
  "mcp": {
    "servers": {
      "logchef": {
        "command": "logchef-mcp",
        "args": [],
        "env": {
          "LOGCHEF_URL": "https://your-logchef-instance.com",
          "LOGCHEF_API_KEY": "your_api_token"
        }
      }
    }
  }
}

For a remote MCP server running in HTTP mode:

{
  "mcp": {
    "servers": {
      "logchef": {
        "type": "http",
        "url": "http://localhost:8000/mcp",
        "headers": {
          "X-Logchef-URL": "https://your-logchef-instance.com",
          "X-Logchef-API-Key": "your_api_token"
        }
      }
    }
  }
}

export LOGCHEF_URL=https://your-logchef-instance.com
export LOGCHEF_API_KEY=your_api_token

codex --mcp-config '{"logchef":{"command":"logchef-mcp","args":[]}}'

Add to your Windsurf MCP configuration:

{
  "mcpServers": {
    "logchef": {
      "command": "logchef-mcp",
      "args": [],
      "env": {
        "LOGCHEF_URL": "https://your-logchef-instance.com",
        "LOGCHEF_API_KEY": "your_api_token"
      }
    }
  }
}

Use the pre-built container image for any client that supports stdio:

{
  "mcpServers": {
    "logchef": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "LOGCHEF_URL",
        "-e", "LOGCHEF_API_KEY",
        "ghcr.io/mr-karan/logchef-mcp:latest",
        "-t", "stdio"
      ],
      "env": {
        "LOGCHEF_URL": "https://your-logchef-instance.com",
        "LOGCHEF_API_KEY": "your_api_token"
      }
    }
  }
}

The -t stdio flag is required because the Docker image defaults to SSE mode.

For SSE or HTTP mode (multi-client scenarios):

# SSE mode
docker run --rm -p 8000:8000 \
  -e LOGCHEF_URL=https://your-logchef-instance.com \
  -e LOGCHEF_API_KEY=your_api_token \
  ghcr.io/mr-karan/logchef-mcp:latest

# Streamable HTTP mode
docker run --rm -p 8000:8000 \
  -e LOGCHEF_URL=https://your-logchef-instance.com \
  -e LOGCHEF_API_KEY=your_api_token \
  ghcr.io/mr-karan/logchef-mcp:latest -t streamable-http

Installation

The MCP server is a standalone Go binary distributed separately from Logchef.

Pre-built binaries — download from the releases page and place in your $PATH.

Docker — docker pull ghcr.io/mr-karan/logchef-mcp:latest

Build from source (requires Go):

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

Available Tools

37 tools organized into 10 categories. Each tool includes MCP annotations indicating whether it is read-only, non-destructive, or destructive.

Profile and Metadata

Tool	Description
`get_profile`	Get current user profile, including email, role, and API token info
`get_teams`	List teams you belong to with your role and member counts
`get_meta`	Server version and configuration details

Source Management

Tool	Description
`get_sources`	All sources accessible to you, aggregated across all team memberships
`get_team_sources`	Sources belonging to a specific team

Log Querying

Tool	Description
`query_logs`	Execute raw ClickHouse SQL against a log source (max 100 rows)
`get_source_schema`	Get column names and ClickHouse types for a source
`get_log_histogram`	Time-series histogram of log volume with optional grouping
`get_collections`	List saved query collections for a team/source
`get_collection`	Get a specific saved query by ID
`create_collection`	Save a new query collection
`update_collection`	Update an existing saved query
`delete_collection`	Delete a saved query permanently

LogchefQL

Tool	Description
`query_logchefql`	Execute a LogchefQL query (max 500 rows)
`translate_logchefql`	Translate LogchefQL to ClickHouse SQL without executing
`validate_logchefql`	Check LogchefQL syntax for errors without executing

Investigation

Tool	Description
`get_field_values`	Top distinct values for a field in a time range
`get_log_context`	Surrounding log entries before/after a timestamp
`list_alerts`	All alert rules configured for a source
`get_alert_history`	Evaluation history for a specific alert

Analysis

Tool	Description
`compare_windows`	Run the same query across two time windows and compare row counts
`top_values`	Get top values for multiple fields in one call

Discovery

Tool	Description
`generate_query`	Generate a ClickHouse SQL query from natural language (requires AI enabled on Logchef)
`get_all_field_dimensions`	Get top values for all LowCardinality fields in one call

Telemetry

Tool	Description
`get_query_telemetry`	Recent query performance from ClickHouse `system.query_log`

Administration (admin only)

Tool	Description
`list_all_teams`	List all teams
`get_team`	Get team details
`create_team`	Create a new team
`update_team`	Update team name/description
`delete_team`	Delete a team permanently
`list_team_members`	List members of a team
`add_team_member`	Add a user to a team with a role
`remove_team_member`	Remove a user from a team
`link_source_to_team`	Grant a team access to a source
`unlink_source_from_team`	Revoke a team’s access to a source
`list_all_users`	List all users
`get_user`	Get user details
`create_user`	Create a user
`update_user`	Update user info
`delete_user`	Delete a user
`list_all_sources`	List all sources
`create_source`	Create a ClickHouse log source
`validate_source_connection`	Test ClickHouse connectivity
`delete_source`	Delete a source
`get_admin_source_stats`	ClickHouse table stats — row count, sizes, compression
`list_api_tokens`	List your API tokens
`create_api_token`	Create a new API token
`delete_api_token`	Delete an API token

Resources

Resources provide read-only data that AI assistants can access without explicit tool calls.

URI Template	Description
`logchef://team/{team_id}/source/{source_id}/schema`	ClickHouse schema for a source
`logchef://team/{team_id}/source/{source_id}/collections`	List of saved queries
`logchef://team/{team_id}/source/{source_id}/collection/{collection_id}`	A single saved query

Prompts

Prompts provide guided multi-step investigation workflows.

`investigate_error_spike`

Walks through error spike diagnosis: schema discovery, error volume assessment, pattern identification, timeline correlation, and root cause analysis.

Argument	Required	Description
`team_id`	Yes	Team ID
`source_id`	Yes	Source ID
`time_range`	No	e.g., “last 1h” (defaults to last 1 hour)

`investigate_alert`

Investigates a specific alert: review configuration, check evaluation history, reproduce the alert query, explore context, and summarize findings.

Argument	Required	Description
`team_id`	Yes	Team ID
`source_id`	Yes	Source ID
`alert_id`	Yes	Alert ID

Tool Configuration

Disable tool categories you do not need to reduce the tool surface exposed to the AI assistant:

# Disable individual categories
logchef-mcp --disable-admin --disable-telemetry

# Or enable only specific categories
logchef-mcp --enabled-tools "profile,sources,logs,logchefql"

Available --disable-* flags:

Flag	Category disabled
`--disable-profile`	Profile and metadata tools
`--disable-sources`	Source management tools
`--disable-logs`	Log querying and collection tools
`--disable-logchefql`	LogchefQL tools
`--disable-investigate`	Investigation tools
`--disable-admin`	Administration tools
`--disable-analysis`	Analysis tools
`--disable-telemetry`	Telemetry tools
`--disable-discover`	Discovery tools

The --enabled-tools flag accepts a comma-separated list of category names: profile, sources, logs, logchefql, investigate, admin, analysis, telemetry, discover. When used, only the listed categories are enabled.

Authentication

Stdio mode (Claude Code, Claude Desktop, Cursor, etc.)

Credentials are passed as environment variables:

export LOGCHEF_URL=https://your-logchef-instance.com
export LOGCHEF_API_KEY=your_api_token

SSE and HTTP modes (remote server)

When running the MCP server as a remote HTTP service, clients can pass credentials via HTTP headers instead of environment variables. This is useful when the server handles multiple clients with different Logchef instances.

Header	Description
`X-Logchef-URL`	Logchef instance URL
`X-Logchef-API-Key`	API token

If headers are not provided, the server falls back to environment variables.

Transport Modes

Mode	Flag	Endpoint	Use case
Stdio	`-t stdio` (default for binary)	—	Direct integration with desktop clients
SSE	`-t sse`	`http://localhost:8000/sse`	Web-based or remote clients
Streamable HTTP	`-t streamable-http`	`http://localhost:8000/mcp`	Multi-client remote setups

Debugging

Enable detailed HTTP request/response logging:

logchef-mcp -debug

logchef-mcp on GitHub Source code, releases, and issue tracker.