使用说明

OpenSearch MCP Server with Tunnel Support

This MCP server provides access to OpenSearch through SSH tunnels, supporting both AWS SSM tunnels and GCP Compute SSH tunnels for secure local access to your OpenSearch cluster.

Prerequisites

For AWS: AWS CLI configured with appropriate profiles
For GCP: gcloud CLI configured
SSH tunnel running (AWS SSM or GCP Compute)
Python 3.11+ with uv package manager

Setup

1. Install Dependencies

uv sync

2. Start the SSH Tunnel

Option A: AWS SSM Tunnel

In your project directory:

make tunnel

This will:

Start an SSM session to the bastion host
Forward localhost:9200 to your OpenSearch endpoint
Keep the tunnel open until you press Ctrl+C

Option B: GCP Compute SSH Tunnel

gcloud compute ssh opensearch-dev --zone=us-central1-a -- -L 9200:127.0.0.1:9200 -L 5601:127.0.0.1:5601

This will:

Create an SSH tunnel to your GCP VM
Forward localhost:9200 to the OpenSearch instance
Forward localhost:5601 to Kibana/OpenSearch Dashboards (optional)

3. Configure the MCP Server

Add to your .mcp.json file:

For AWS OpenSearch Serverless

{
  "mcpServers": {
    "opensearch": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/opensearch-mcp",
        "run",
        "mcp",
        "run",
        "main.py"
      ],
      "env": {
        "OPENSEARCH_HOST": "localhost",
        "OPENSEARCH_PORT": "9200",
        "OPENSEARCH_USE_AWS_AUTH": "true",
        "OPENSEARCH_USE_SSM_TUNNEL": "true",
        "OPENSEARCH_USE_SSL": "true",
        "OPENSEARCH_ENDPOINT": "your-endpoint.us-west-2.aoss.amazonaws.com",
        "AWS_PROFILE": "your-aws-profile",
        "AWS_REGION": "us-west-2"
      }
    }
  }
}

For GCP OpenSearch (via Compute SSH tunnel)

{
  "mcpServers": {
    "opensearch": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/opensearch-mcp",
        "run",
        "mcp",
        "run",
        "main.py"
      ],
      "env": {
        "OPENSEARCH_HOST": "localhost",
        "OPENSEARCH_PORT": "9200",
        "OPENSEARCH_USE_AWS_AUTH": "false",
        "OPENSEARCH_USE_SSM_TUNNEL": "true",
        "OPENSEARCH_USE_SSL": "false"
      }
    }
  }
}

Configuration

The server supports the following environment variables:

Connection Settings

OPENSEARCH_HOST: Tunnel host (default: localhost)
OPENSEARCH_PORT: Tunnel port (default: 9200)
OPENSEARCH_USE_SSL: Use SSL/HTTPS (default: true). Set to false for plain HTTP connections
OPENSEARCH_VERIFY_CERTS: Verify SSL certificates (default: false)
OPENSEARCH_TIMEOUT: Connection timeout in seconds (default: 30)

Tunnel Settings

OPENSEARCH_USE_SSM_TUNNEL: Enable tunnel mode (default: true). Works for both AWS SSM and GCP Compute tunnels
OPENSEARCH_ENDPOINT: The actual OpenSearch endpoint (mainly for AWS, optional for GCP)

AWS Authentication (for AWS OpenSearch Serverless)

OPENSEARCH_USE_AWS_AUTH: Enable AWS authentication (default: true). Set to false for GCP or non-AWS deployments
AWS_PROFILE: AWS profile to use for authentication
AWS_REGION: AWS region (default: us-west-2)
AWS_SERVICE: AWS service name (default: aoss for OpenSearch Serverless)

Available Tools

The MCP server provides the following tools:

Cluster Operations

check_cluster_health: Check the health of the OpenSearch cluster

Index Management

list_indices: List all indices in the cluster
describe_index: Get detailed information about an index
create_index: Create a new index with optional mappings, settings, and aliases
delete_index: Delete an index
update_index_mapping: Update the mapping of an existing index (can only add new fields)
reindex_data: Reindex data from one index to another with optional query filtering and scripting

Alias Management

list_index_aliases: List all aliases or aliases for a specific index
create_index_alias: Create an alias for an index with optional filter query and routing
delete_index_alias: Delete an alias from an index

Document Operations

search: Search documents in an index
index_document: Index a new document
delete_document: Delete a document by ID

Example Usage

# List all indices
await list_indices(ctx)

# Create a new index with mappings and settings
await create_index(ctx,
    index_name="my_index",
    mappings={
        "properties": {
            "title": {"type": "text"},
            "timestamp": {"type": "date"}
        }
    },
    settings={
        "number_of_shards": 1,
        "number_of_replicas": 1
    }
)

# Update index mapping (add new fields only)
await update_index_mapping(ctx,
    index_name="my_index",
    mappings={
        "properties": {
            "new_field": {"type": "keyword"}
        }
    }
)

# Create an alias
await create_index_alias(ctx,
    index_name="my_index",
    alias_name="my_alias",
    filter_query={"term": {"status": "active"}}
)

# List all aliases
await list_index_aliases(ctx)

# Reindex data from one index to another
await reindex_data(ctx,
    source_index="old_index",
    dest_index="new_index",
    query={"range": {"timestamp": {"gte": "2024-01-01"}}}
)

# Search for documents
await search(ctx,
    index_name="sars",
    query={"match": {"status": "DRAFT"}},
    size=10
)

# Get index information
await describe_index(ctx, index_name="sars")

# Delete an alias
await delete_index_alias(ctx,
    index_name="my_index",
    alias_name="my_alias"
)

# Delete an index
await delete_index(ctx, index_name="my_index")

Testing

Test the Connection

# Test the OpenSearch connection through the tunnel
python scripts/opensearch/test_connection.py dev

# Test the MCP server
uv run python test_mcp_server.py

Verify SSM Tunnel

# Check if port 9200 is open
nc -zv localhost 9200

# Test with curl
curl -k https://localhost:9200/_cat/indices

Troubleshooting

SSM Tunnel Not Running

Error: Port 9200 is not open. The SSM tunnel is not running.

Solution: Start the tunnel with make tunnel in your project directory.

AWS Credentials Expired

Error: Failed to get AWS credentials

Solution: Refresh your AWS SSO credentials:

aws sso login --profile your-aws-profile

404 Errors on Root Path

This is expected behavior for OpenSearch Serverless. The root path (/) returns 404, but index operations work normally.

Connection Refused

Ensure the SSM tunnel is running and port 9200 is not blocked by another process.

Architecture

┌─────────────┐     ┌──────────────┐     ┌─────────────┐     ┌────────────────┐
│  MCP Client │────▶│  MCP Server  │────▶│ SSM Tunnel  │────▶│   OpenSearch   │
│   (Claude)  │     │  (main_aws)  │     │ localhost:  │     │   Serverless   │
└─────────────┘     └──────────────┘     │    9200     │     └────────────────┘
                           │              └─────────────┘
                           │                     │
                           └─────────────────────┘
                            AWS SigV4 Auth

The MCP server:

Connects to localhost:9200 (SSM tunnel)
Uses AWS SigV4 authentication
Sets the Host header to route to the correct OpenSearch endpoint
Provides a simple interface for OpenSearch operations

Security

All traffic goes through the secure SSM tunnel
AWS IAM authentication is used for all requests
No credentials are stored locally
SSL/TLS encryption for all communications