Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/elastic--gemini-cli-elasticsearch/badge.svg)](/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

i

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)

  1. 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.
  2. Connects directly to Elasticsearch using:
  3. - Model Context Protocol (MCP)
  4. - Agent Skills (using the `skills.js` script)
  5. > [!CAUTION]
  6. > This extension is currently experimental.
  7. ## Installation & Setup
  8. 1. Install the **elasticsearch** extension:
  9. ```sh
  10. gemini extensions install https://github.com/elastic/gemini-cli-elasticsearch
  11. ```
  12. 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):
  13. - Get your MCP server URL from **Agents > View all tools > Manage MCP > Copy MCP Server URL**
  14. - The URL will look like: `https://your-deployment.kb.region.gcp.elastic.cloud/api/agent_builder/mcp`
  15. 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.
  16. Otherwise, you can create a [standard Elasticsearch API key](https://www.elastic.co/docs/deploy-manage/api-keys/elasticsearch-api-keys):
  17. - In Kibana: **Stack Management > Security > API Keys > Create API key**
  18. - Copy the **encoded** API key value
  19. 4. Set the required environment variables in your shell:
  20. ```sh
  21. export ELASTIC_URL="your-elasticsearch-url"
  22. export ELASTIC_MCP_URL="your-elasticsearch-mcp-url"
  23. export ELASTIC_API_KEY="your-encoded-api-key"
  24. ```
  25. To make these permanent, add them to your shell config file (`~/.bashrc`, `~/.zshrc`, `~/.config/fish/config.fish`, etc.)
  26. 5. Verify the extension is installed and active:
  27. ```sh
  28. gemini extensions list
  29. ```
  30. 6. Verify the MCP server connection:
  31. ```sh
  32. gemini mcp list
  33. ```
  34. You should see `✓ elastic-agent-builder ... - Connected`
  35. 7. (Optional) Install Agent Skills using the `skills.js` script -- see [Install Elastic Skills](#install-elastic-skills) below.
  36. 8. Test with a query using MCP:
  37. ```sh
  38. gemini chat "list my elasticsearch indices"
  39. ```
  40. ## Usage with MCP
  41. 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).
  42. ### Example Queries
  43. ```sh
  44. gemini chat "show me all my elasticsearch indices"
  45. gemini chat "search for documents about 'error' in my logs"
  46. gemini chat "what fields are in my user-data index?"
  47. gemini chat "show me the top 10 error codes from my logs this week"
  48. ```
  49. ### Available Tools
  50. | Tool | Description |
  51. | -------- | -------- |
  52. | `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. |
  53. | `platform_core.get_document_by_id` | Retrieve the full content (source) of an Elasticsearch document based on its ID and index name. |
  54. | `platform_core.get_index_mapping` | Retrieve mappings for the specified index or indices. |
  55. | `platform_core.index_explorer` | List relevant indices, aliases and datastreams based on a natural language query. |
  56. | `platform_core.list_indices` | List the indices, aliases and datastreams from the Elasticsearch cluster. |
  57. | `platform_core.execute_esql` | Execute an ES\|QL query and return the results in a tabular format. |
  58. | `platform_core.generate_esql` | Generate an ES\|QL query from a natural language query. |
  59. ### Available commands
  60. This extension exposes Gemini commands to directly call MCP tools.
  61. | Command | Description |
  62. | ------- | ----------- |
  63. | `/elastic:list-indices` | List the indices, aliases and datastreams from the Elasticsearch cluster. |
  64. | `/elastic:explore-indices` | List relevant indices, aliases and datastreams based on a natural language query. |
  65. | `/elastic:get-mapping` | Retrieve mappings for the specified index or indices. |
  66. | `/elastic:search-dsl`| Search the Elasticsearch cluster using DSL queries |
  67. | `/elastic:search-esql` | Search the Elasticsearch cluster using ES\|QL queries generated by the MCP server |
  68. ## Troubleshooting
  69. **If `gemini mcp list` shows "Disconnected":**
  70. - Verify environment variables are set: `echo $ELASTIC_MCP_URL` and `echo $ELASTIC_API_KEY`
  71. - Open a new terminal window to reload environment variables
  72. - Check Agent Builder is enabled in Kibana
  73. - Verify your API key hasn't expired
  74. **Authentication errors:**
  75. - Ensure you're using the **encoded** API key format
  76. - Check the key has proper permissions in Kibana
  77. ## Install Elastic Skills
  78. 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.
  79. You can list, select and install the Elastic skills using the following terminal command:
  80. ```sh
  81. node ~/.gemini/extensions/elasticsearch/skills.js --install --interactive
  82. ```
  83. If you are in the Gemini CLI terminal, remember to use `!` as a prefix for the command.
  84. For more information about the `skills.js` script you can read the [dedicated page](SKILLS_INSTALL.md).
  85. ## Disabling MCP when using skills
  86. Since some skills may overlap with the tools available on the `elastic-agent-builder` MCP server, you can disable it:
  87. ```sh
  88. /mcp disable elastic-agent-builder
  89. ```
  90. To re-enable it: `/mcp enable elastic-agent-builder`
  91. ## Support
  92. For more help, see the [Elastic Community Forums](https://discuss.elastic.co/)
  93. ## License
  94. This software is licensed under the [Apache License 2.0](./LICENSE). See [NOTICE](./NOTICE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.