Kibana MCP Server

API Blueprint Reference

This utility is architected referencing the official Elastic Kibana API documentation, dynamically acquiring endpoint configurations by leveraging the OpenAPI YAML specification provided by Elastic Stack version 8.x (ES8). For exhaustive documentation on the underlying APIs, consult the Kibana API documentation.

An MCP server implementation designed to bridge Kibana accessibility for any MCP-aware client (e.g., Claude Desktop) through conversational or structured queries.

Disclaimer: This software is maintained by the community and is not officially endorsed by Elastic or the MCP framework.

🚀 Deployment Guide

Rapid Installation

# Global installation (recommended practice)
npm install -g @tocharian/mcp-server-kibana

# Or local dependency integration
npm install @tocharian/mcp-server-kibana

Source Code Checkout

git clone https://github.com/TocharianOU/mcp-server-kibana.git
cd mcp-server-kibana
npm install
npm run build

🎯 Operational Initialization

Approach 1: Command Line Interface (CLI)

Utilizing Credential-Based Access

# Configure Kibana endpoint details and execute
KIBANA_URL=http://your-kibana-server:5601 \
KIBANA_USERNAME=your-username \
KIBANA_PASSWORD=your-password \
npx @tocharian/mcp-server-kibana

# Configure session identifiers and execute
KIBANA_URL=http://your-kibana-server:5601 \
KIBANA_COOKIES="sid=your-session-id; security-session=your-security-session" \
npx @tocharian/mcp-server-kibana

Approach 2: Integration with Claude Desktop (Preferred)

Integrate the following configuration into your Claude Desktop settings file:

Configuration File Paths: - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - Windows: %APPDATA%\Claude\claude_desktop_config.json

Credential Mode Configuration Snippet

{
  "mcpServers": {
    "kibana-gateway": {
      "command": "npx",
      "args": ["@tocharian/mcp-server-kibana"],
      "env": {
        "KIBANA_URL": "http://your-kibana-server:5601",
        "KIBANA_USERNAME": "your-username",
        "KIBANA_PASSWORD": "your-password",
        "KIBANA_DEFAULT_SPACE": "default",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

{
  "mcpServers": {
    "kibana-gateway": {
      "command": "npx",
      "args": ["@tocharian/mcp-server-kibana"],
      "env": {
        "KIBANA_URL": "http://your-kibana-server:5601",
        "KIBANA_COOKIES": "sid=your-session-id; security-session=your-security-session",
        "KIBANA_DEFAULT_SPACE": "default",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

Approach 3: Environment Variable File Injection

# Define parameters in a configuration file
cat > kibana-config.env << EOF
KIBANA_URL=http://your-kibana-server:5601
KIBANA_USERNAME=your-username
KIBANA_PASSWORD=your-password
NODE_TLS_REJECT_UNAUTHORIZED=0
EOF

# Execute using environment sourcing
env $(cat kibana-config.env | xargs) npx @tocharian/mcp-server-kibana

Approach 4: HTTP Streaming Interface (Introduced v0.4.0)

Activate the server as a persistent HTTP service for external integration and remote access:

# Start HTTP service (default port 3000)
MCP_TRANSPORT=http \
KIBANA_URL=http://your-kibana-server:5601 \
KIBANA_USERNAME=your-username \
KIBANA_PASSWORD=your-password \
npx @tocharian/mcp-server-kibana

# Or specify host/port bindings
MCP_TRANSPORT=http \
MCP_HTTP_PORT=9000 \
MCP_HTTP_HOST=0.0.0.0 \
KIBANA_URL=http://your-kibana-server:5601 \
KIBANA_USERNAME=your-username \
KIBANA_PASSWORD=your-password \
npx @tocharian/mcp-server-kibana

HTTP Mode Capabilities: - Exposes the MCP protocol endpoint at http://host:port/mcp - Status endpoint available at http://host:port/health for monitoring - Implements robust session handling with unique identifiers - Supports both synchronous POST requests (JSON-RPC) and asynchronous GET requests (Server-Sent Events streams) - Fully compatible with standard HTTP clients and existing MCP SDKs

Sample HTTP Client Interaction (JavaScript):

// Initiate session
const sessionInit = await fetch('http://localhost:3000/mcp', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'initialize',
    params: {
      protocolVersion: '2024-11-05',
      capabilities: {},
      clientInfo: { name: 'my-client', version: '1.0.0' }
    },
    id: 1
  })
});

const sessionId = sessionInit.headers.get('mcp-session-id');

// Subsequent operations require the session ID in the header
const toolsRequest = await fetch('http://localhost:3000/mcp', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'mcp-session-id': sessionId
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'tools/list',
    params: {},
    id: 2
  })
});

Key Capabilities

Foundational Features

Connectivity established with both local and remote Kibana endpoints
Dual Communication Protocols:
Stdio (Default): Optimized for local MCP clients like Claude Desktop.
Streamable HTTP: Enables remote access, API integration, and web-based client support.
Authentication Versatility:
Session Cookie reliance (Recommended for browser-based continuity).
Standard Basic Authentication (Username/Password).
Support for encrypted transport (SSL/TLS) and custom certificate authority integration.
Comprehensive handling of multi-tenancy (spaces) within enterprise Kibana setups.
Kibana API endpoints exposed both as callable tools and addressable resources.
Capacity to query, examine, and trigger Kibana APIs directly from MCP clients.
Architecture designed for type safety, extensibility, and streamlined integration.
HTTP Mode Specifics: Automated UUID generation for session tracking and a dedicated health monitoring interface.
Health Check Endpoint available for service uptime validation.

Visualization Layer (VL) Capabilities

Full Create, Read, Update, Delete (CRUD) support for Kibana's persistent objects (saved objects).
Generic Saved Object Management - Applicable across all object schemas.
Adaptive Input Parsing: Intelligent handling of parameters using various formats (JSON strings, arrays, delimited lists) to improve user experience.
Performance Enhancements: Optimized search mechanisms incorporating pagination capabilities.
Efficiency Tools: Functionality for executing multiple updates or deletions in batch operations.
Concurrency Control: Implementation of versioning mechanisms to ensure safe, optimistic updates.
Dependency Mapping: Tools to manage object relationships (references).
Flexible Data Ingestion: Robust parsing logic supporting diverse input structures for enhanced usability.

Project Layout

├── index.ts                # Primary server bootstrap file
├── src/
│   ├── types.ts            # Data contracts and schema definitions
│   ├── base-tools.ts       # Core tool registration and API execution logic
│   ├── prompts.ts          # Definitions for expert and resource assistant prompts
│   ├── resources.ts        # Registration of discoverable API paths/URIs
│   ├── vl_search_tools.ts  # Visualization Layer - Search utilities
│   ├── vl_get_tools.ts     # Visualization Layer - Retrieval utilities
│   ├── vl_create_tools.ts  # Visualization Layer - Creation utilities
│   ├── vl_update_tools.ts  # Visualization Layer - Modification utilities
│   └── vl_delete_tools.ts  # Visualization Layer - Removal utilities
├── kibana-openapi-source.yaml # Source manifest for Kibana API specifications
├── README.md               # Primary English documentation
├── README_zh.md            # Chinese language documentation

Discoverable Resources

Resource URI	Description
`kibana-api://paths`	Fetches the complete roster of accessible Kibana API endpoints (supports `search` filtering)
`kibana-api://path/{method}/{encoded_path}`	Retrieves detailed specification for a designated API segment

Usage Examples: - kibana-api://paths?search=saved_objects - kibana-api://path/GET/%2Fapi%2Fstatus

Available Tools

Core Utilities

Tool Identifier	Functionality Description	Required Inputs
`get_status`	Retrieve operational status of the Kibana host instance	`space` (Optional string specifying the target context)
`execute_kb_api`	Invoke an arbitrary Kibana API endpoint call	`method` (GET/POST/PUT/DELETE), `path` (URI string), `body` (Optional JSON payload), `params` (Optional query parameters), `space` (Optional context)
`get_available_spaces`	Enumerate accessible Kibana organizational spaces	`include_details` (Optional boolean flag for verbose output)
`search_kibana_api_paths`	Filter the API registry based on keyword matching	`search` (String term for matching)
`list_all_kibana_api_paths`	Output the entire registry of exposed Kibana APIs	None
`get_kibana_api_detail`	Fetch specific metadata for one API path/method pair	`method` (String identifier), `path` (String identifier)

Visualization Layer (VL) Tools - Persistent Object Administration

Tool Identifier	Functionality Description	Required Inputs
`vl_search_saved_objects`	Universal search across all types of stored objects	`types` (Array of object types), `search` (Optional term), `fields` (Optional list), `perPage` (Optional), `page` (Optional), `space` (Optional context)
`vl_get_saved_object`	Retrieve a specific object using its type and unique identifier	`type` (Mandatory type string), `id` (Mandatory identifier), `useResolve` (Optional boolean), `space` (Optional context)
`vl_create_saved_object`	Instantiate a new persistent object (schema-agnostic)	`type` (Mandatory type string), `attributes` (Mandatory data payload), `id` (Optional), `overwrite` (Optional boolean), `references` (Optional dependency list), `space` (Optional context)
`vl_update_saved_object`	Apply modifications to an existing object	`type` (Mandatory type string), `id` (Mandatory identifier), `attributes` (Mandatory changes), `references` (Optional dependency list), `version` (Optional ETag/version for concurrency), `space` (Optional context)
`vl_bulk_update_saved_objects`	Process multiple object modifications concurrently	`objects` (Array of objects requiring updates), `space` (Optional context)
`vl_bulk_delete_saved_objects`	Initiate removal of several objects in one transaction	`objects` (Array of objects targeted for deletion), `force` (Optional boolean for hazardous deletion), `space` (Optional context)

Recognized Persistent Object Types: dashboard, visualization, index-pattern, search, config, lens, map, tag, canvas-workpad, canvas-element

Assistant Prompts

Prompt Name	Utility Description
`kibana-tool-expert`	Activates expert mode for tool invocation, enabling sophisticated analysis, execution, and clarification of Kibana operations. Recommended for most interactive sessions.
`kibana-resource-helper`	Activates guidance mode focusing on leveraging server resource URIs. Best suited for clients limited to resource access or scenarios requiring raw API metadata retrieval.

Operational Configuration

Environmental parameters control the gateway's behavior:

Kibana Connectivity Parameters

Parameter Name	Purpose	Mandatory	Default Setting
`KIBANA_URL`	Address of the target Kibana server (e.g., https://kibana.corp:5601)	Yes	N/A
`KIBANA_USERNAME`	Identifier for Basic Authentication usage	No*	N/A
`KIBANA_PASSWORD`	Secret for Basic Authentication usage	No*	N/A
`KIBANA_COOKIES`	Session identifier string for cookie-based access	No*	N/A
`KIBANA_DEFAULT_SPACE`	Initial context space (default: 'default')	No	'default'
`KIBANA_CA_CERT`	File path to a custom Certificate Authority bundle for SSL trust	No	N/A
`KIBANA_TIMEOUT`	Request expiration threshold in milliseconds (default 30000)	No	30000
`KIBANA_MAX_RETRIES`	Maximum attempts for transient requests (default 3)	No	3
`NODE_TLS_REJECT_UNAUTHORIZED`	Set to `0` to permit connections using self-signed certificates (use with extreme caution)	No	N/A

*Authentication requires either KIBANA_COOKIES or both KIBANA_USERNAME and KIBANA_PASSWORD.

Communication Protocol Settings (v0.4.0+)

| Parameter Name | Function | Default | Permitted Values | |-------------------|------------------------------------------------|-----------|-----------------|| | MCP_TRANSPORT | Selection of the I/O method | stdio | stdio, http | | MCP_HTTP_PORT | Listening TCP port when in HTTP mode | 3000 | 1-65535 | | MCP_HTTP_HOST | Network interface binding when in HTTP mode | localhost | Any resolvable host address |

Protocol Specifics: - Stdio Mode: Standard input/output channel, suitable for direct execution environments. - HTTP Mode: Functions as a standalone network service, enabling remote invocation and integration.

📦 Distribution Metadata

NPM Package Reference: @tocharian/mcp-server-kibana
Source Code Repository: TocharianOU/mcp-server-kibana
Required Node.js Version: >= 18.0.0
Bundle Size: Approx. 685KB (6.4MB expanded)

🔧 Diagnostic Assistance

Resolving Common Failures

'import: command not found' Error

# Ensure the utility is updated to the latest version
npm install -g @tocharian/mcp-server-kibana@latest

# Alternatively, invoke directly via the Node runtime
node $(which mcp-server-kibana)

Connectivity Failures

Verify the network path to the specified Kibana URL is clear.
Double-check provided authentication credentials.
If certificate errors occur, consider setting NODE_TLS_REJECT_UNAUTHORIZED=0 temporarily.

Claude Desktop Detection Issues

Perform a full restart of the Claude Desktop application after modifying configuration files.
Validate the structural integrity of the JSON configuration using a validator.
Confirm that the environmental settings passed to the process are correctly established.

Illustrative Query Examples

Fundamental Operations

"Ascertain the current operational status of the Kibana host."
"What is the status report for the 'operations' space?"
"Generate a list of all accessible Kibana organizational contexts."
"Provide the comprehensive directory of all exposed Kibana API pathways."
"Detail the specification for the API path matching POST /api/saved_objects/_find."
"Execute a raw API call targeting the /api/status endpoint."

Persistent Object Administration

"Inventory all stored dashboards across the instance."
"Locate any visualizations whose titles contain the term 'web-traffic'."
"Retrieve the specific saved object identified as 'app-metrics-config-789'."
"Provision a new dashboard titled 'Yearly Performance Summary'."
"Modify the description attribute for visualization ID 'viz-456'."
"Initiate bulk removal for several outdated configuration entries by their IDs."
"Search for Lens documents within the 'reporting' space."
"List all Canvas workpads that were finalized within the current calendar month."
"Fetch the first 10 index patterns, limiting output to only their unique ID and title."
"Perform a mass update on several dashboard titles concurrently."
"Query across both visualization and dashboard objects simultaneously."
"Define a new index pattern schema for 'app_events-*' designating 'event_time' as the time field."

Dual Interaction Models in Claude Desktop

When utilized alongside Claude Desktop, this gateway supports two distinct modes of interaction:

1. Tool Invocation Protocol

Mechanism: Claude Desktop invokes callable server tools directly (e.g., get_status, execute_api, or specialized VL tools like vl_search_saved_objects, vl_create_saved_object). The server executes the action and returns the result.
Advantage: Provides a highly conversational and guided interaction experience. The gateway intelligently mediates API calls and object management actions on behalf of the user.
Use Case Example: "Display all error logs from the last hour" or "Construct a new visualization tracking user logins."
Testing Tip: Set the prompt selection in Claude Desktop to kibana-tool-expert to begin testing this functionality.

2. Resource Abstraction Protocol

Mechanism: Interaction occurs via the defined resource URIs (e.g., kibana-api://paths or kibana-api://path/GET/%2Fapi%2Fstatus). The server responds by serving the requested structured metadata.
Advantage: Maximizes compatibility for MCP clients that possess native resource parsing capabilities or when raw API metadata is required.
Use Case Example: "Fetch resource kibana-api://paths?search=dashboard"

Compatibility Note: The presence of both base tools and corresponding resources (list_all_kibana_api_paths maps to kibana-api://paths) ensures seamless integration across different MCP client capabilities, simplifying adoption for tools like Claude Desktop.

Recommendation: Users seeking the most intuitive and powerful engagement should favor the tool-based mode; resource mode is reserved for advanced integration or client compatibility requirements.

Engineering & Contribution

Prerequisite installation:

npm install

To compile the production assets:

npm run build

Enable continuous compilation during development:

npm run watch

Execution commands:

# Default Stdio communication
npm start

# HTTP Service Mode
npm run start:http

# Development mode running TypeScript directly
npm run start:ts

# HTTP Mode running TypeScript directly
npm run start:http:ts

Diagnostic Tools

Debugging standard I/O communication can be complex. The recommended approach involves using the specialized MCP Inspector utility:

npm run inspector

Once initiated, Inspector will publish a URL accessible via a web browser, providing a dedicated interface for tracing communication flows.

Community Guidelines

This project thrives on community involvement. All submissions and discussions must adhere to a respectful and constructive ethos, following the guidelines set forth in the Elastic Community Code of Conduct.

Licensing Information

This software is distributed under the terms of the Apache License, Version 2.0. Consult the LICENSE file for the complete legal text.

Persistent Problem Resolution

Confirm the validity and structure of the MCP configuration setup.
Verify external network connectivity to the designated Kibana endpoint.
Validate that the authenticating identity possesses necessary operational permissions.
If leveraging a custom CA, confirm the certificate file path is correct and accessible by the process.
Exercise caution if bypassing SSL checks via NODE_TLS_REJECT_UNAUTHORIZED=0.
Scrutinize terminal output for detailed error diagnostics.

WIKIPEDIA: Enterprise management solutions encompass the systems, applications, controls, computational frameworks, methodologies, and procedures utilized by organizations to navigate evolving market dynamics, secure a competitive footing, and enhance overall organizational effectiveness.

== Conceptual Framework == Management tools are often segmented according to the functional areas of an enterprise, classifying them by roles such as strategic planning aids, process orchestration utilities, data record-keeping mechanisms, human resource adjuncts, decision support systems, and performance monitoring controls. A functional categorization typically addresses these general operational pillars:

Utilities facilitating data acquisition and integrity checks across all operational units. Software designed for governing and refining organizational workflows. Systems aggregating data for strategic analysis and executive decision formulation. The evolution of modern management software has been exponential over the preceding decade, driven by rapid technological leaps, making optimal selection challenging for any given corporate context. This complexity arises from the continuous drive to reduce operational expenditure while maximizing revenue generation, coupled with the imperative to deeply understand customer demands and deliver conforming products precisely as requested. In this environment, executives must adopt a forward-looking perspective on enterprise management tooling, rather than simply adopting the newest available solution. Over-reliance on uncustomized tools often results in systemic instability. Business management software requires meticulous selection, followed by thorough adaptation to the specific requirements of the organization, rather than forcing the organization to conform to the software's inherent structure.

== Prevalent Tools == Data from a 2013 Bain & Company survey indicated the global utilization patterns of management tools. These patterns reflect the outcomes necessary to satisfy regional and market conditions. The ten most frequently cited tools included:

Strategic roadmap development Client Relationship Management (CRM) Staff sentiment assessment surveys Comparative performance analysis (Benchmarking) Balanced Scorecard methodology Core capability identification Operational outsourcing strategies Organizational transition management programs Product flow orchestration (SCM) Articulated organizational purpose (Mission/Vision) Market segment delineation Comprehensive quality assurance (TQM)

== Business Software Applications == A set of interconnected software programs employed by personnel to execute diverse corporate functions is termed business software or a business application. These applications are deployed to augment productivity metrics, quantify performance, and execute specialized corporate tasks with precision. This evolution began with Management Information Systems (MIS), progressed into integrated Enterprise Resource Planning (ERP) suites, subsequently incorporated Customer Relationship Management (CRM) modules, and has now largely transitioned into cloud-based enterprise management platforms. While a tangible link exists between Information Technology investment and organizational efficacy, two critical factors determine the realized value addition: the proficiency of the implementation process and the careful selection and tailoring of the supporting technologies.

== Tools Tailored for Small and Medium Enterprises (SMEs) == Tools specifically engineered for SMEs are crucial as they offer pathways to conserve limited...

kibana-access-gateway-mcp

Author

TocharianOU

Quick Info

Actions

Tags