elasticsearch
Official Elasticsearch extension for Gemini CLI
Open source Open in the app JSON README (API)
About
Official Elasticsearch extension for Gemini CLI
Details
- Kind
- Plugins
- Topic
- Databases
- Publisher
- elastic
- Origin
- gemini
- Category
- ferramentas
- Version
- 0.3.0
- Stars
- 118
- Forks
- 3
- Last push
- 2026-04-08T06:32:09Z
- Repository state
- ativo
- Language
- JavaScript
- License
- Apache-2.0
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-08-30 14:13:39
- Origin id
elastic/gemini-cli-elasticsearch
README
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).