opensearch-mcp-integration

madhankb/opensearch-mcp-integration

3.2

If you are the rightful owner of opensearch-mcp-integration and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Model Context Protocol (MCP) server facilitates seamless integration between natural language processing tools and OpenSearch, enabling efficient data interaction and management.

Tools
16
Resources
0
Prompts
0

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:

  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