Humio MCP Server

A Model Context Protocol (MCP) server implementation for Humio, enabling integration with Humio's logging and analytics platform.

Description

This project implements a server that bridges the Model Context Protocol with Humio's logging capabilities. It allows for seamless integration between applications and Humio's powerful logging and analytics features.

Prerequisites

• Humio token

Installation

1. Clone the repository:

git clone [repository-url]
cd humio-mcp

2. Install dependencies:

npm install

or

pnpm install

or

yarn install

3. Create a .env file in the root directory with your Humio configuration (this is only useful for dev/testing as the MCP client will provide the env variables anyway):

HUMIO_API_TOKEN=your_api_token
HUMIO_REQUEST_TIMEOUT_MS=30000

4. Create config from the example config file

cp humio-query-config.example.json humio-query-config.json

Usage

Build the server:

npm run build

or

pnpm run build

or

yarn run build

Inspection

After building, you can inspect the server using the MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Connect to the client. Sample config

"humioMCP": {
    "command": "node",
    "args": [
        "<absolute-path-to-server>/humio-mcp/dist/index.js"
    ],
    "type": "stdio",
    "env": {
        "HUMIO_API_TOKEN": "<HUMIO_API_TOKEN>",
        "HUMIO_REQUEST_TIMEOUT_MS": 3000
    }
}

Configuration File Format

The humio-query-config.json file defines the available queries for the server. Each entry in the array should follow the structure below:

Field	Type	Required	Description
name	string	Yes	Unique name for the query configuration.
description	string	Yes	Human-readable description of what the query does.
query	string	Yes	The Humio query string, can include template variables (e.g., {{variableName}}).
fields	string[]	Yes	List of fields to extract from the query results.
variables	Variable[]	No	List of variables required by the query. See below for the Variable format.
outputTemplate	string	Yes	Template for formatting each result. Uses {{fieldName}} for interpolation.
joinString	string	Yes	String used to join multiple formatted results.

Variable Format

Each item in the variables array can be one of the following:

Scalar Variable

Field	Type	Required	Description
name	string	Yes	Name of the variable.
description	string	Yes	Description of the variable.
type	'string'|'number'|'boolean'	Yes	Type of the variable.
required	boolean	Yes	Whether the variable is required.

Enum Variable

Field	Type	Required	Description
name	string	Yes	Name of the variable.
description	string	Yes	Description of the variable.
type	'enum'	Yes	Type of the variable (must be 'enum').
required	boolean	Yes	Whether the variable is required.
enumOptions	string[]	Yes	Allowed values for the enum variable.

Example

[
  {
    "name": "criticalErrors",
    "description": "Finds critical errors for the banana team grouped by message and stack trace.",
    "query": "k8s.labels.team = banana | (severity = crit ) | groupBy([message, stack_trace])",
    "fields": ["message", "stack_trace", "_count"],
    "outputTemplate": "Error \"{{message}}\" occurred in total: {{_count}} times. The Stack trace is \n---{{stack_trace}}\n---\n\n",
    "joinString": "\n"
  },
  {
    "name": "projectOperationsByState",
    "description": "Groups operations by state for a given project in the banana team.",
    "query": "k8s.labels.team = banana | projectKey=\"{{projectKey}}\" | groupBy([fields.state])",
    "fields": ["fields.state", "_count"],
    "variables": [
      {
        "name": "projectKey",
        "description": "The project key to filter by.",
        "type": "string",
        "required": true
      }
    ],
    "outputTemplate": "state: {{fields.state}} - {{_count}} operations",
    "joinString": "\n"
  }
]

⚠️ Danger: Sensitive Information

Do NOT include any sensitive information in the fields field of your configuration.

The contents of the fields field are returned to the client and may be passed to a Large Language Model (LLM). Any sensitive data (such as API keys, passwords, personal information, or confidential business data) included here could be exposed.

Ensure that only non-sensitive, safe-to-share information is specified in the fields field of your config files.

⚠️ Warning: Timeout and Partial Results

If the configured timeout (HUMIO_REQUEST_TIMEOUT_MS) is reached during a query, the server will return the events collected up to that point. This means the results may be incomplete and might not capture all relevant events.

To reduce the risk of missing data, consider adjusting the timeout value according to your expected query size and network conditions.

Project Structure

humio-mcp/
├── src/
│   ├── humio/                  # Humio-specific implementations
│   ├── utils/                  # Utility functions
│   └── index.ts                # Main server entry point
├── dist/                       # Compiled JavaScript files
├── humio-query-config.json     # Configurations for available quries
├── package.json                # Project dependencies and scripts
└── tsconfig.json               # TypeScript configuration