gemini-cli-elasticsearch
Official Elasticsearch extension for Gemini CLI
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/elastic--gemini-cli-elasticsearch)HTML
<a href="/listings/elastic--gemini-cli-elasticsearch"><img src="/api/listings/elastic--gemini-cli-elasticsearch/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
1. Install the **elasticsearch** extension: ```sh 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](https://www.elastic.co/docs/explore-analyze/ai-features/agent-builder/tools#copy-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](https://github.com/elastic/start-local) you already have the API key in the start-local `.env` file. Otherwise, you can create a [standard Elasticsearch API key](https://www.elastic.co/docs/deploy-manage/api-keys/elasticsearch-api-keys): - 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:
```sh 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:
```sh gemini extensions list ```
6. Verify the MCP server connection:
```sh gemini mcp list ```
You should see `✓ elastic-agent-builder ... - Connected`
7. (Optional) Install Agent Skills using the `skills.js` script -- see [Install Elastic Skills](#install-elastic-skills) below.
8. Test with a query using MCP:
```sh gemini chat "list my elasticsearch indices" ```
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 136 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- The official Elasticsearch extension for the [Gemini CLI](https://github.com/google-gemini/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)
- > [!CAUTION]
- > This extension is currently experimental.
- ## Installation & Setup
- 1. Install the **elasticsearch** extension:
- ```sh
- 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](https://www.elastic.co/docs/explore-analyze/ai-features/agent-builder/tools#copy-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](https://github.com/elastic/start-local) you already have the API key in the start-local `.env` file.
- Otherwise, you can create a [standard Elasticsearch API key](https://www.elastic.co/docs/deploy-manage/api-keys/elasticsearch-api-keys):
- - 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:
- ```sh
- 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:
- ```sh
- gemini extensions list
- ```
- 6. Verify the MCP server connection:
- ```sh
- gemini mcp list
- ```
- You should see `✓ elastic-agent-builder ... - Connected`
- 7. (Optional) Install Agent Skills using the `skills.js` script -- see [Install Elastic Skills](#install-elastic-skills) below.
- 8. Test with a query using MCP:
- ```sh
- 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
- ```sh
- 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](https://github.com/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:
- ```sh
- 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](SKILLS_INSTALL.md).
- ## 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:
- ```sh
- /mcp disable elastic-agent-builder
- ```
- To re-enable it: `/mcp enable elastic-agent-builder`
- ## Support
- For more help, see the [Elastic Community Forums](https://discuss.elastic.co/)
- ## License
- This software is licensed under the [Apache License 2.0](./LICENSE). See [NOTICE](./NOTICE).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.