madhankb/opensearch-mcp-integration

OpenSearch MCP <> LLM Integration Guide

This guide provides step-by-step instructions for integrating Amazon Q & Anthropic Claude desktop with OpenSearch using MCP servers for natural language interactions.

Anthropic Claude

Amazon Q

Prerequisites

• Docker and Docker Compose installed
• Python 3.x installed
• pipx installed (pip install pipx)
• Amazon Q CLI
• Anthropic Claude Desktop

1. Setting up Local OpenSearch Instance

1. Create a new directory for your project:

   mkdir opensearch-mcp && cd opensearch-mcp
   

2. Create a docker-compose.yml file with the following content:

   version: '3'
   services:
     opensearch:
       image: opensearchproject/opensearch:latest
       environment:
         - discovery.type=single-node
         - bootstrap.memory_lock=true
         - "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m"
         - "OPENSEARCH_INITIAL_ADMIN_PASSWORD=myStrongPassword123!"
         - "plugins.security.ssl.http.enabled=true"
         - "plugins.security.ssl.transport.enabled=true"
         - "plugins.security.ssl.http.pemcert_filepath=certs/node.pem"
         - "plugins.security.ssl.http.pemkey_filepath=certs/node-key.pem"
         - "plugins.security.ssl.http.pemtrustedcas_filepath=certs/root-ca.pem"
         - "plugins.security.ssl.transport.pemcert_filepath=certs/node.pem"
         - "plugins.security.ssl.transport.pemkey_filepath=certs/node-key.pem"
         - "plugins.security.ssl.transport.pemtrustedcas_filepath=certs/root-ca.pem"
       ulimits:
         memlock:
           soft: -1
           hard: -1
         nofile:
           soft: 65536
           hard: 65536
       volumes:
         - opensearch-data:/usr/share/opensearch/data
         - ./certs:/usr/share/opensearch/config/certs
       ports:
         - 9200:9200
         - 9600:9600
       networks:
         - opensearch-net
   
     opensearch-dashboards:
       image: opensearchproject/opensearch-dashboards:latest
       environment:
         - 'OPENSEARCH_HOSTS=["https://opensearch:9200"]'
         - "OPENSEARCH_SSL_VERIFICATIONMODE=none"
         - "OPENSEARCH_SECURITY_ADMIN_PASSWORD=myStrongPassword123!"
         - "SERVER_SSL_ENABLED=true"
         - "SERVER_SSL_CERTIFICATE=/usr/share/opensearch-dashboards/config/certs/node.pem"
         - "SERVER_SSL_KEY=/usr/share/opensearch-dashboards/config/certs/node-key.pem"
       ports:
         - 5601:5601
       volumes:
         - ./certs:/usr/share/opensearch-dashboards/config/certs
       depends_on:
         - opensearch
       networks:
         - opensearch-net
   
   volumes:
     opensearch-data:
   
   networks:
     opensearch-net:
   

3. Start the containers:

   docker compose up -d
   

2. Installing OpenSearch MCP Server

1. Install the OpenSearch MCP server using pipx:

   pipx install opensearch-mcp-server
   

3. Configuring LLMs with MCP server configurations

1. Amazon Q: Create a mcp.json file in your Amazon Q configuration directory (~/.aws/amazonq/mcp.json)

2. Anthropic Claude: Create a claude_desktop_config.json file in your Claude Desktop configuration directory (~/Library/Application Support/Claude/claude_desktop_config.json)

   {
     "mcpServers": {
       "opensearch-mcp-server": {
         "command": "/Users/YOUR_USERNAME/.local/bin/opensearch-mcp-server",
         "args": [],
         "env": {
           "OPENSEARCH_URL": "https://localhost:9200",
           "OPENSEARCH_SSL_VERIFY": "none",
           "OPENSEARCH_USERNAME": "admin",
           "OPENSEARCH_PASSWORD": "myStrongPassword123!"
         }
       }
     }
   }
   

   Replace YOUR_USERNAME with your system username or specify the location where the opensearch-mcp-server is installed.

4. Verifying the Setup

1. Check OpenSearch is running:

   curl -XGET -u admin:myStrongPassword123! https://localhost:9200
   

2. Verify OpenSearch Dashboards:

   • Open https://localhost:5601 in your browser

3. Check indices:

   curl -XGET -u admin:myStrongPassword123! https://localhost:9200/_cat/indices
   

5. Using Natural Language with OpenSearch

Here are some example commands you can try in LLMs:

1. Create an index:

   Create a new index called "books" with title and author fields
   

2. Add documents:

   Add a document to the books index with title "The Great Gatsby" and author "F. Scott Fitzgerald"
   

3. Search documents:

   Search for books by F. Scott Fitzgerald
   

4. Get index information:

   Show me the mapping of the books index
   

Troubleshooting

1. If MCP server fails to initialize:

   • Check if OpenSearch is running (docker ps)
   • Verify credentials in mcp_config.json
   • Check OpenSearch logs (docker compose logs opensearch)

2. If tools are not available:

   • Restart the LLMs
   • Check MCP server logs
   • Verify the mcp_config.json syntax

Available MCP Tools

The OpenSearch MCP server provides several tools for interacting with OpenSearch:

• list_indices: List all indices.
• get_index: Returns information (mappings, settings, aliases) about one or more indices. Args: index: Name of the index
• create_index: Create a new index. Args: index: Name of the index body: Optional index configuration including mappings and settings
• delete_index: Delete an index. Args: index: Name of the index
• search_documents: Search for documents. Args: index: Name of the index body: Search query
• index_document: Creates or updates a document in the index. Args: index: Name of the index document: Document data id: Optional document ID
• get_document: Get a document by ID. Args: index: Name of the index id: Document ID
• delete_document: Delete a document by ID. Args: index: Name of the index id: Document ID
• delete_by_query: Deletes documents matching the provided query. Args: index: Name of the index body: Query to match documents for deletion
• get_cluster_health: Returns basic information about the health of the cluster.
• get_cluster_stats: Returns high-level overview of cluster statistics.
• list_aliases: List all aliases.
• get_alias: Get alias information for a specific index. Args: index: Name of the index
• put_alias: Create or update an alias for a specific index. Args: index: Name of the index name: Name of the alias body: Alias configuration
• delete_alias: Delete an alias for a specific index. Args: index: Name of the index name: Name of the alias
• general_api_request: Perform a general HTTP API request. Use this tool for any Elasticsearch/OpenSearch API that does not have a dedicated tool. Args: method: HTTP method (GET, POST, PUT, DELETE, etc.) path: API endpoint path params: Query parameters body: Request body

Security Notes

1. Always use strong passwords in production
2. Enable SSL in production environments
3. Regularly rotate credentials

Additional Resources

• OpenSearch Documentation
• Amazon Q Documentation
• MCP Protocol Documentation