es_mcp_server

# Elasticsearch MCP Server This project implements an MCP (Model Context Protocol) server for Elasticsearch, providing tools and resources to interact with Elasticsearch clusters. [](https://opensource.org/licenses/MIT) ## Features ### Tools - `list_indices`: Lists all indices in the Elasticsearch cluster - `get_mappings`: Gets the mappings for a specific index - `search`: Performs an Elasticsearch search with a provided query DSL - `search_with_query_string`: Performs a search with a simple query string - `get_index_stats`: Gets statistics for a specific index ### Resources - `elasticsearch://indices`: Lists all Elasticsearch indices - `elasticsearch://index/{index_name}`: Gets detailed information about a specific index - `elasticsearch://mapping/{index_name}`: Gets mapping information for a specific index ## Prerequisites - Python 3.7+ - Elasticsearch Python client - MCP SDK - Elasticsearch cluster credentials (Cloud ID and API Key) ## Setup 1. Clone the repository: ``` git clone https://github.com/yourusername/elasticsearch-mcp-server.git cd elasticsearch-mcp-server ``` 2. Install the required dependencies: ``` pip install -r requirements.txt ``` 3. Set up environment variables: - Copy the example environment file: `cp .env.example .env` - Edit the `.env` file and add your Elasticsearch credentials Or set them directly in your shell: ``` export ES_CLOUD_ID=your_elasticsearch_cloud_id export ES_API_KEY=your_elasticsearch_api_key ``` ## Configuring the MCP Server for Claude The `configure_mcp_server.py` script helps you set up the Elasticsearch MCP server in Claude's MCP settings file. This allows Claude to connect to your Elasticsearch cluster through the MCP server. ```bash python configure_mcp_server.py your_cloud_id your_api_key ``` This script: 1. Takes your Elasticsearch Cloud ID and API Key as command-line arguments 2. Locates or creates the Claude MCP settings file 3. Adds or updates the Elasticsearch MCP server configuration 4. Sets the environment variables needed for the server to connect to your Elasticsearch cluster After running this script, restart VS Code to apply the changes. Claude will then be able to use the Elasticsearch MCP server to interact with your Elasticsearch cluster. ## Testing the MCP Resources ### Option 1: Using the Test Script We've provided a test script that starts the MCP server and provides instructions for testing: ```bash # Make the script executable if needed chmod +x test_es_mcp.sh # Run the test script ES_CLOUD_ID=your_cloud_id ES_API_KEY=your_api_key ./test_es_mcp.sh ``` The script will: 1. Start the MCP server in the background 2. Provide instructions for testing the resources 3. Keep the server running until you press Ctrl+C ### Option 2: Manual Testing 1. Start the MCP server: ```bash ES_CLOUD_ID=your_cloud_id ES_API_KEY=your_api_key python es_mcp_server.py ``` 2. In Claude, use the `access_mcp_resource` tool to access the resources: a. List all indices: ``` <access_mcp_resource> <server_name>elasticsearch-mcp-server</server_name> <uri>elasticsearch://indices</uri> </access_mcp_resource> ``` b. Get information about a specific index: ``` <access_mcp_resource> <server_name>elasticsearch-mcp-server</server_name> <uri>elasticsearch://index/your_index_name</uri> </access_mcp_resource> ``` c. Get mapping for a specific index: ``` <access_mcp_resource> <server_name>elasticsearch-mcp-server</server_name> <uri>elasticsearch://mapping/your_index_name</uri> </access_mcp_resource> ``` ### Option 3: Using the Python Test Script We've also provided a Python test script that demonstrates how to access the resources: ```bash ES_CLOUD_ID=your_cloud_id ES_API_KEY=your_api_key python test_es_resources.py ``` ## Resource Details ### `elasticsearch://indices` Returns a JSON array of all indices in the Elasticsearch cluster, including: - Index name - Health status - Status - Document count - Size ### `elasticsearch://index/{index_name}` Returns detailed information about a specific index, including: - Index name - Settings - Statistics (document count, size in bytes and MB) ### `elasticsearch://mapping/{index_name}` Returns mapping information for a specific index, including: - Complete mapping definition - Field count - Field type distribution ## Error Handling All resources include proper error handling and validation: - If an index doesn't exist, the resource will return an appropriate error message - If there's an issue connecting to Elasticsearch, the resource will return an error message - All exceptions are caught and returned as readable error messages ## Contributing Contributions are welcome! Here's how you can contribute: 1. Fork the repository 2. Create a feature branch: `git checkout -b feature/your-feature-name` 3. Commit your changes: `git commit -am 'Add some feature'` 4. Push to the branch: `git push origin feature/your-feature-name` 5. Submit a pull request ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.