README.md

The official Elasticsearch extension for the Gemini CLI to search, retrieve, and analyze Elasticsearch data in developer and agentic workflows.

Connects directly to Elasticsearch using:

• Model Context Protocol (MCP)
• Agent Skills (using the skills.js script)

Installation & Setup

1. Install the elasticsearch extension:

   gemini extensions install https://github.com/elastic/gemini-cli-elasticsearch
   

2. To use the Elastic Agent Builder MCP server (on Elastic Serverless or 9.3+) you need your MCP server URL:

   • Get your MCP server URL from Agents > View all tools > Manage MCP > Copy MCP Server URL
   • The URL will look like: https://your-deployment.kb.region.gcp.elastic.cloud/api/agent_builder/mcp

3. You need an API key. If you are running Elasticsearch with start-local you already have the API key in the start-local .env file. Otherwise, you can create a standard Elasticsearch API key:

   • In Kibana: Stack Management > Security > API Keys > Create API key
   • Copy the encoded API key value

4. Set the required environment variables in your shell:

   export ELASTIC_URL="your-elasticsearch-url"
   export ELASTIC_MCP_URL="your-elasticsearch-mcp-url"
   export ELASTIC_API_KEY="your-encoded-api-key"
   

   To make these permanent, add them to your shell config file (~/.bashrc, ~/.zshrc, ~/.config/fish/config.fish, etc.)

5. Verify the extension is installed and active:

   gemini extensions list
   

6. Verify the MCP server connection:

   gemini mcp list
   

   You should see ✓ elastic-agent-builder ... - Connected

7. (Optional) Install Agent Skills using the skills.js script -- see Install Elastic Skills below.

8. Test with a query using MCP:

   gemini chat "list my elasticsearch indices"
   

Usage with MCP

Once installed with an active connection to the Elasticsearch MCP server, the elasticsearch extension automatically invokes available Tools as part of your natural language query input (where each Tool invocation is displayed as part of the CLI output response).

Example Queries

gemini chat "show me all my elasticsearch indices"
gemini chat "search for documents about 'error' in my logs"
gemini chat "what fields are in my user-data index?"
gemini chat "show me the top 10 error codes from my logs this week"

Available Tools

Tool	Description
platform_core.search	Used for finding documents, counting, aggregating, or summarizing data from a known index. Supports both full-text relevance searches and structured analytical queries.
platform_core.get_document_by_id	Retrieve the full content (source) of an Elasticsearch document based on its ID and index name.
platform_core.get_index_mapping	Retrieve mappings for the specified index or indices.
platform_core.index_explorer	List relevant indices, aliases and datastreams based on a natural language query.
platform_core.list_indices	List the indices, aliases and datastreams from the Elasticsearch cluster.
platform_core.execute_esql	Execute an ES|QL query and return the results in a tabular format.
platform_core.generate_esql	Generate an ES|QL query from a natural language query.

Available commands

This extension exposes Gemini commands to directly call MCP tools.

Command	Description
/elastic:list-indices	List the indices, aliases and datastreams from the Elasticsearch cluster.
/elastic:explore-indices	List relevant indices, aliases and datastreams based on a natural language query.
/elastic:get-mapping	Retrieve mappings for the specified index or indices.
/elastic:search-dsl	Search the Elasticsearch cluster using DSL queries
/elastic:search-esql	Search the Elasticsearch cluster using ES|QL queries generated by the MCP server

Troubleshooting

If gemini mcp list shows "Disconnected":

• Verify environment variables are set: echo $ELASTIC_MCP_URL and echo $ELASTIC_API_KEY
• Open a new terminal window to reload environment variables
• Check Agent Builder is enabled in Kibana
• Verify your API key hasn't expired

Authentication errors:

• Ensure you're using the encoded API key format
• Check the key has proper permissions in Kibana

Install Elastic Skills

From version 0.3.0+, the Elastic skills are not automatically installed in the Gemini extension. We released a dedicated elastic/agent-skills repository, which provides skills for Elasticsearch, Kibana, Observability, Security, and Elastic Cloud.

You can list, select and install the Elastic skills using the following terminal command:

node ~/.gemini/extensions/elasticsearch/skills.js --install --interactive

If you are in the Gemini CLI terminal, remember to use ! as a prefix for the command.

For more information about the skills.js script you can read the dedicated page.

Disabling MCP when using skills

Since some skills may overlap with the tools available on the elastic-agent-builder MCP server, you can disable it:

/mcp disable elastic-agent-builder

To re-enable it: /mcp enable elastic-agent-builder

Support

For more help, see the Elastic Community Forums

License

This software is licensed under the Apache License 2.0. See NOTICE.