example-mcp-dashbuilder

An MCP (Model Context Protocol) app that lets AI assistants build Kibana dashboards using ES|QL and Elastic Charts. Create visualizations through natural language, preview them live with Kibana’s grid layout, and export directly to Kibana as real Lens dashboards.

Screenshot from Claude Desktop: the MCP app renders the interactive dashboard inside the chat.

What it does

You (in an MCP client) → "Build me an ecommerce analytics dashboard"
    ↓
AI explores your Elasticsearch data via ES|QL
    ↓
Creates charts (bar, line, pie, metric, heatmap) with Elastic Charts
    ↓
Interactive dashboard rendered inline in the chat (MCP Apps)
    ↓
One-click export to Kibana as Lens visualizations

Features

• Natural language dashboard creation — describe what you want, the AI builds it
• Deep data analysis — open-ended exploration flow that runs aggregations, surfaces patterns, builds charts for key findings, and suggests drill-down queries (triggered by prompts like “analyze my X”)
• ES|QL powered — all queries use ES|QL for data retrieval
• Inline dashboard preview — full interactive dashboard rendered directly in the chat via MCP Apps
• Kibana grid layout — same 48-column drag-and-drop grid as Kibana dashboards
• Borealis theme — matches Kibana’s latest visual design
• Collapsible sections — organize panels into groups
• Export to Kibana — creates real Kibana dashboards with Lens visualizations
• Import from Kibana — import existing ES|QL-based Kibana dashboards for AI-assisted editing
• Custom color themes — apply custom palettes to charts, heatmaps, and metrics
• Time picker — filter data by time range with automatic time field detection
• Multiple dashboards — create, switch between, and manage multiple dashboards
• Session isolation — parallel chat conversations work on separate dashboards via dashboardId threading
• Elastic Cloud support — works with local Elasticsearch and Elastic Cloud (Cloud ID + API key)
• Server instructions — workflow, tips, and capabilities exposed to every MCP client via the initialize response
• Dataviz best practices — built-in guidelines for chart selection and dashboard composition
• ES|QL reference — built-in language reference for correct query syntax

Architecture

For a structured walkthrough with Mermaid diagrams (system context, data flows, monorepo build order), see ARCHITECTURE.md.

Prerequisites

• Node.js 22+
• Elasticsearch (local or Elastic Cloud)
• Kibana (for export/import)
• An MCP client: Cursor (v2.6+ for MCP Apps inline preview), Claude Desktop, Claude Code, or VS Code Copilot

Quick install

No need to clone the repo — pick the method that matches your MCP client.

Claude Desktop: Download the latest .mcpb file from GitHub Releases and double-click it. Claude Desktop will prompt you for your Elasticsearch credentials.

Cursor / Claude Code / VS Code: Point your MCP config at the release tarball — no clone, no npm install:

{
  "mcpServers": {
    "example-mcp-dashbuilder": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "https://github.com/elastic/example-mcp-dashbuilder/releases/latest/download/example-mcp-dashbuilder.tgz"
      ]
    }
  }
}

Set your Elasticsearch credentials as environment variables (ES_NODE, ES_API_KEY or ES_USERNAME/ES_PASSWORD, KIBANA_URL) or run npm run setup after cloning.

Setup (from source)

1. Install dependencies

git clone https://github.com/elastic/example-mcp-dashbuilder.git
cd example-mcp-dashbuilder
npm install

This also auto-builds the MCP App (the inline dashboard preview).

2. Configure Elasticsearch connection

Run the setup wizard to configure your Elasticsearch and Kibana credentials:

npm run setup

The wizard supports both local and Elastic Cloud deployments:

• Local: Elasticsearch URL + username/password
• Elastic Cloud: Cloud ID + username/password or API key

Credentials are saved to a .env file (gitignored).

3. Configure your MCP client

No environment variables are needed if you ran npm run setup — credentials are loaded from .env automatically.

The repo includes a start-server.sh script that handles nvm/node path resolution automatically. This is the recommended way to configure the server.

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "example-mcp-dashbuilder": {
      "type": "stdio",
      "command": "./start-server.sh"
    }
  }
}

Claude Code (.mcp.json in project root — already included):

{
  "mcpServers": {
    "example-mcp-dashbuilder": {
      "type": "stdio",
      "command": "./start-server.sh"
    }
  }
}

Claude Desktop (claude_desktop_config.json — found in ~/Library/Application Support/Claude/ on macOS or %APPDATA%\Claude\ on Windows):

For the easiest experience, download the .mcpb file from Releases. For manual setup from source:

{
  "mcpServers": {
    "example-mcp-dashbuilder": {
      "command": "/absolute/path/to/example-mcp-dashbuilder/start-server.sh"
    }
  }
}

Note: Claude Desktop requires an absolute path.

4. Open the project in your MCP client

Open the example-mcp-dashbuilder folder in your MCP client. The MCP server will auto-connect. In Cursor, you should see it listed in Settings > MCP.

Troubleshooting

• npx: command not found — Cursor/Claude Desktop may not inherit your shell PATH when launched from the dock. Either open your client from the terminal (e.g. cursor .) or use the start-server.sh script which loads nvm automatically.
• EPERM: operation not permitted — Claude Desktop’s macOS sandbox blocks access to ~/Documents. Move the repo to a non-protected location like ~/example-mcp-dashbuilder or /tmp.
• Wrong Node version — The project requires Node 22+. If you use nvm, start-server.sh handles this. For manual config, use the full path to your Node binary: /Users/you/.nvm/versions/node/v22.x.x/bin/node.

Usage

Example prompts

Quick start:

“Build me a dashboard from kibana_sample_data_ecommerce with revenue metrics, order trends, and category breakdowns”

Detailed:

“Create a new dashboard called ‘Flight Operations’. Show metrics for total flights, average delay, and cancellation rate. Add a bar chart of flights by carrier, a line chart of delays over time, and a pie chart of flight status distribution. Organize into sections.”

Exploratory:

“Explore the kibana_sample_data_logs index and build me the most insightful dashboard you can”

Analysis:

“Analyze my logs data”

“What’s interesting in the ecommerce orders index?”

Export / Import:

“Export the current dashboard to Kibana”

“Import the Kibana dashboard at http://localhost:5601/app/dashboards#/view/abc-123”

Multi-dashboard:

“List my dashboards” / “Switch to the ecommerce dashboard” / “Create a new dashboard called ‘Log Analysis’”

Available MCP tools

Available MCP resources

Supported chart types

HTTP transport

Start the server in HTTP mode:

npm run start -- --http

The server listens on http://127.0.0.1:3001/mcp by default. Override with environment variables:

HOST=127.0.0.1 PORT=3002 npm run start -- --http

Inline dashboard preview (MCP Apps)

The view_dashboard tool renders the full interactive dashboard directly inside the chat using MCP Apps.

Client requirements: Cursor v2.6+, Claude Desktop, Claude.ai, or VS Code Copilot.

Export to Kibana

The export tool translates each panel to a Lens visualization:

Grid positions are preserved 1:1 (same 48-column system). ES|QL queries transfer directly. Time fields are auto-detected via field_caps so Kibana’s time picker works immediately. Custom colors (series palettes, metric backgrounds, heatmap ramps) are preserved on export.

Credits

• Elastic Charts for visualization rendering
• @elastic/esql for ES|QL query parsing
• kbn-grid-layout for the dashboard grid (adapted from Kibana)
• Model Context Protocol for AI tool integration
• MCP Apps for inline UI rendering
• ES|QL reference docs adapted from Kibana’s NL-to-ES|QL feature

Licence

Licensed under Elastic License 2.0.