Kibana MCP Server

API Blueprint

This utility is built against the official Elastic Kibana API reference documentation, dynamically ingesting the OpenAPI YAML schema from Elastic Stack 8.x (ES8) to dynamically enumerate and govern all accessible Kibana endpoints. Refer to the primary Kibana API documentation for definitive external details.

An implementation of the MCP server proxy designed to bridge any MCP-compliant consumer (such as Claude Desktop) to your designated Kibana environment through interpretive or explicit requests.

This package is a community initiative and does not represent official backing from Elastic or the MCP framework.

---

🚀 Setup Instructions

Rapid Acquisition

bash

Install globally for system-wide access (suggested)

npm install -g @tocharian/mcp-server-kibana

Or incorporate locally within a project dependency tree

npm install @tocharian/mcp-server-kibana

Compilation from Source

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

---

🎯 Quick Initiation

Option 1: Command Line Interface (CLI) Execution

Employing Basic Credentials

bash

Configure connection parameters and invoke

KIBANA_URL=http://your-kibana-server:5601 \ KIBANA_USERNAME=your-user \ KIBANA_PASSWORD=your-secret \ npx @tocharian/mcp-server-kibana

Utilizing Session Cookies

bash

Configure active session tokens and invoke

KIBANA_URL=http://your-kibana-server:5601 \ KIBANA_COOKIES="sid=your-token-id; security-session=your-auth-token" \ npx @tocharian/mcp-server-kibana

Option 2: Integration with Claude Desktop (Preferred)

Incorporate the following configuration snippet into your Claude Desktop configuration file:

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

Configuration Example: Basic Authentication

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

Option 4: Streaming HTTP Interface (New since v0.4.0)

Operate the service as a dedicated web endpoint for remote API ingress and integration:

bash

Initiate HTTP gateway (defaults to port 3000)

MCP_TRANSPORT=http \ KIBANA_URL=http://your-kibana-server:5601 \ KIBANA_USERNAME=your-user \ KIBANA_PASSWORD=your-secret \ npx @tocharian/mcp-server-kibana

Or customize network 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-user \ KIBANA_PASSWORD=your-secret \ npx @tocharian/mcp-server-kibana

HTTP Gateway Capabilities: - Exposes the MCP conduit at http://host:port/mcp. - Status check endpoint: http://host:port/health. - Manages stateful connections via session tokens. - Accepts POST requests (JSON-RPC protocol) and GET requests (Server-Sent Events). - Broad compatibility with any standard HTTP client or MCP software development kit.

---

Key Capabilities

Foundational Features

• Connectivity to local or remote Kibana instances.
• Dual Communication Methods:
• Standard I/O (Default): Optimized for direct interaction with Claude Desktop/local MCP consumers.
• HTTP Stream (v0.4.0+): Facilitates external API access, web embedding, and distributed systems integration.
• Authentication Flexibility:
• Cookie-based sessions (preferred for authenticated browser contexts).
• Username/Password credentials.
• Support for securing transport via SSL/TLS and custom certificate authorities.
• Comprehensive handling of multi-tenant Kibana spaces.
• Exposure of all discoverable Kibana API routes as both executable tools and queryable resources.
• Session Management (HTTP Mode) via dynamic UUID assignment.
• Integrated health monitoring interface.

Visualization Layer (VL) Functionality

• Full Create, Read, Update, Delete (CRUD) lifecycle management for Kibana's persisted objects.
• Holistic Object Coverage - manages every supported object kind within Kibana.
• Flexible Input Handling - robust parsing for parameter formats (JSON payloads, arrays, delimited strings).
• Performance Tuning - supports paginated retrieval and optimization directives for searches.
• Batch Operations for efficient bulk modification or removal.
• Concurrency Control via optimistic locking for safe updates.
• Reference Graph Management for maintaining object dependencies.

---

Directory Map

├── index.ts # Primary server execution file ├── src/ │ ├── types.ts # Schema definitions and data structures │ ├── base-tools.ts # Core tool registration and backend logic │ ├── prompts.ts # Definitions for expert and resource helper prompts │ ├── resources.ts # Registration of API path resources/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 file for API specification ingestion ├── README.md # English Documentation ├── README_zh.md # Chinese Documentation

---

Available Endpoints (Resources)

| Resource URI | Purpose | Operation Details | |------------------------------------------------|----------------------------------------------------| | kibana-api://paths | Lists all accessible Kibana API routes (supports search filter) | Query with kibana-api://paths?search=pattern | | kibana-api://path/{method}/{encoded_path} | Retrieves metadata for a precise API route | Example: kibana-api://path/GET/%2Fapi%2Fstatus |

---

Integrated Functions (Tools)

Foundational Interaction Set

Tool Name	Action Description	Parameters
get_status	Query the operational state of the Kibana service	space (Optional string for scoping)
execute_kb_api	Invoke an arbitrary Kibana API call	method (HTTP verb), path (URI), body (Payload optional), params (Query parameters optional), space (Scope optional)
get_available_spaces	Retrieve accessible Kibana workspaces	include_details (Optional boolean)
search_kibana_api_paths	Filter API routes based on a keyword	search (Required string)
list_all_kibana_api_paths	Dump the complete registry of API endpoints	None
get_kibana_api_detail	Obtain granular specifications for one endpoint	method (string), path (string)

Visualization Layer (VL) Utilities for Saved Objects

Tool Name	Action Description	Parameters
vl_search_saved_objects	Universal search across specified object types	types (Array of types), search (Query string), fields (Projection), perPage/page (Pagination), space (Scope)
vl_get_saved_object	Fetch a single persistent object by ID and Type	type, id, useResolve (Optional reference resolution), space (Scope)
vl_create_saved_object	Provision a new saved object instance	type, attributes (Required properties), id (Optional ID assignment), overwrite (Optional boolean), references (Dependencies), space (Scope)
vl_update_saved_object	Modify the properties of an existing object	type, id, attributes (Changes), version (For optimistic locking), space (Scope)
vl_bulk_update_saved_objects	Apply modifications to several objects simultaneously	objects (Array of update payloads), space (Scope)
vl_bulk_delete_saved_objects	Erase multiple objects in a single batch operation	objects (Array of objects to delete), force (Optional skip checks), space (Scope)

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

---

Prompt Directives

Directive Name	Functionality
kibana-tool-expert	Activates the primary interaction mode. Enables sophisticated analysis, execution via tools, and detailed explanation of Kibana operations. Recommended default for robust interaction.
kibana-resource-helper	Guides clients that exclusively support resource retrieval, providing raw API metadata via resource URIs. Useful for clients lacking native tool invocation capability.

---

Operational Parameters

Configuration is managed via environment variables:

Kibana Connectivity Parameters

Variable Name	Purpose	Mandatory
KIBANA_URL	The base endpoint for the target Kibana instance.	Yes
KIBANA_USERNAME	Credentials for Basic Authentication.	No*
KIBANA_PASSWORD	Secret for Basic Authentication.	No*
KIBANA_COOKIES	Session tokens required for Cookie Authentication.	No*
KIBANA_DEFAULT_SPACE	Initial context space (defaults to 'default').	No
KIBANA_CA_CERT	File path to a custom Certificate Authority bundle.	No
KIBANA_TIMEOUT	Maximum wait time for responses, in milliseconds (30s default).	No
NODE_TLS_REJECT_UNAUTHORIZED	Set to 0 to bypass SSL certificate validity checks (Security risk acknowledged).	No

*Authentication requires either KIBANA_COOKIES OR both KIBANA_USERNAME and KIBANA_PASSWORD.

Communication Protocol Parameters (v0.4.0+)

Variable Name	Selection	Default	Valid Selections
MCP_TRANSPORT	Defines how the server communicates.	stdio	stdio, http
MCP_HTTP_PORT	TCP port for HTTP mode operation.	3000	1 to 65535
MCP_HTTP_HOST	Network interface to bind to in HTTP mode.	localhost	Any bindable address

---

Package Metadata

• NPM Registry: @tocharian/mcp-server-kibana
• Source Code: TocharianOU/mcp-server-kibana
• Prerequisite Node.js: Version 18.0.0 or newer
• Bundle Footprint: Approximately 685KB compressed (6.4MB installed size)

---

Debugging & Support

Common Connectivity Hurdles

Error: "import: command not found"

bash

Ensure your global package cache is current

npm install -g @tocharian/mcp-server-kibana@latest

Alternatively, invoke via the node runtime directly

node $(which mcp-server-kibana)

Connection Failures

• Cross-check the provided Kibana server URL for correctness.
• Re-validate all authentication tokens or credentials.
• If SSL is involved, confirm certificate trust paths or temporarily use the bypass flag (NODE_TLS_REJECT_UNAUTHORIZED=0).

Claude Desktop Detection Failure

• Perform a full restart of the Claude Desktop application after configuration edits.
• Validate the JSON syntax of your configuration file using an external validator.
• Verify that environment variables are correctly propagated to the running client process.

---

Sample Inquiries

Fundamental Checks

• "What is the operational status of the Kibana host?"
• "Query the status of the Kibana instance within the 'operations' space."
• "List all namespaces accessible to me."
• "Enumerate all discoverable Kibana API entry points."
• "Provide specifications for the POST /api/saved_objects/_find route."
• "Dispatch a raw API invocation targeting /api/status."

Persistence Management (VL Tools)

• "Retrieve a listing of all dashboard configurations."
• "Locate visualizations whose titles reference 'error_rate'."
• "Fetch the details for the object ID 'dashboard-XYZ-999'."
• "Provision a new data view named 'app_events_2025' targeting data indices matching 'app-*'."
• "Modify the metadata for the visualization 'viz-456'."
• "Remove all saved searches that are older than 90 days using a bulk operation."
• "Search concurrently for index patterns and maps within the 'reporting' space."

---

Interaction Modalities in Claude Desktop

This server supports two distinct interaction paradigms when integrated with Claude Desktop:

1. Tool Invocation Mode (Recommended for Conversational Use)

• Mechanism: Claude Desktop invokes the server's defined tools (get_status, vl_create_saved_object, etc.) to fulfill user requests, automatically translating natural language into structured API calls.
• Benefit: Provides a guided, intelligent interaction flow where the server manages the complexities of Kibana API structure and execution.
• Directive Mapping: Best utilized with the kibana-tool-expert directive.
• Test Pattern: Initiate use after setting the kibana-tool-expert prompt in Claude Desktop.

2. Resource Access Mode (For Metadata Retrieval)

• Mechanism: The client accesses structured data by requesting server resources (e.g., kibana-api://paths). The server returns the raw metadata in a format Claude can internally parse.
• Benefit: Offers maximum flexibility and is suitable for clients restricted to resource fetching or advanced scripting scenarios.
• Directive Mapping: Aligns well with the kibana-resource-helper directive.

Design Note: The dualism between the Resources table and the Tools table ensures compatibility. Base tools like list_all_kibana_api_paths correspond directly to the primary resources, ensuring MCP clients that favor one access pattern over the other can still function effectively.

---

Development Lifecycle

Required dependencies installation:

bash npm install

Build artifacts:

bash npm run build

Continuous compilation for active development:

bash npm run watch

Execution variants:

bash

Default I/O execution

npm start

HTTP Gateway execution

npm run start:http

Development execution (live TypeScript)

npm run start:ts

HTTP Gateway with live TypeScript compilation

npm run start:http:ts

---

Debugging

Direct stdio debugging can be challenging. Utilize the dedicated inspection utility:

bash npm run inspector

This command launches a browser interface that offers transparency into the MCP communication stream.

---

Community Engagement

This project thrives on open contribution. Maintain a professional and welcoming demeanor in all interactions, adhering to the guidelines set forth in the Elastic Community Code of Conduct.

---

Licensing

Distributed under the terms of the Apache License 2.0. Consult the LICENSE file for comprehensive specifics.

---

Self-Diagnosis Checklist

• Verify MCP configuration paths are accurate.
• Confirm network reachability to the Kibana server address.
• Ensure authentication entities possess necessary permissions.
• If using custom security, confirm the CA certificate path is valid and accessible.
• Exercise caution when utilizing NODE_TLS_REJECT_UNAUTHORIZED=0.
• Scrutinize terminal output for detailed error reports.

OVERVIEW: Cloud infrastructure signifies a methodology that permits scalable, adaptable access to shared computational assets (virtual or physical) via a network, characterized by immediate provisioning and self-management, frequently termed "the cloud" per ISO standards.

== Core Attributes == As defined by NIST in 2011, cloud systems possess five foundational attributes. The precise NIST assertions are:

On-demand self-service: "A consumer can unilaterally provision computing capabilities, such as server time and network storage, as needed automatically without requiring human interaction with each service provider." Broad network access: "Capabilities are available over the network and accessed through standard mechanisms that promote use by heterogeneous thin or thick client platforms (e.g., mobile phones, tablets, laptops, and workstations)." Resource pooling: " The provider's computing resources are pooled to serve multiple consumers using a multi-tenant model, with different physical and virtual resources dynamically assigned and reassigned according to consumer demand." Rapid elasticity: "Capabilities can be elastically provisioned and released, in some cases automatically, to scale rapidly outward and inward commensurate with demand. To the consumer, the capabilities available for provisioning often appear unlimited and can be appropriated in any quantity at any time." Measured service: "Cloud systems automatically control and optimize resource use by leveraging a metering capability at some level of abstraction appropriate to the type of service (e.g., storage, processing, bandwidth, and active user accounts). Resource usage can be monitored, controlled, and reported, providing transparency for both the provider and consumer of the utilized service. ISO subsequently provided refinements and expansions to this list by 2023.

== Historical Context ==

The trajectory of cloud computing traces back to the 1960s, marked by the ascendance of time-sharing concepts facilitated by remote job entry (RJE). The dominant model then involved centralized data centers where users submitted tasks to operators managing mainframe systems. This era concentrated on pioneering methods to democratize access to high-capacity computation through time-sharing, thereby enhancing infrastructure, platform, and application efficiency for the end user. The figurative use of "the cloud" to denote virtualized provisioning emerged around 1994, employed by General Magic to depict the aggregate of accessible locations within their Telescript programming environment for mobile agents. David Hoffman, a communications specialist at General Magic, is credited with this metaphor, which drew upon its prior established use in telecommunications. The specific term "cloud computing" gained broader recognition in 1996 when Compaq Computer Corporation drafted a strategic blueprint centered on emerging Internet capabilities. The enterprise aimed to significantly enhance...