OpenSearch MCP Server

A Model Context Protocol (MCP) server built with FastMCP for retrieving error stack traces by transaction ID (TID) from OpenSearch logs.

Features

• Error stack trace retrieval: Get complete error stack traces by transaction ID (TID)
• Docker-based setup: Easy local development with Docker Compose
• Environment variable configuration: Flexible connection settings via environment variables

Prerequisites

• Python 3.10 or higher
• Docker and Docker Compose (for running the MCP server in a container)
• An accessible OpenSearch instance (you provide your own)
• pip or uv for package management

Installation

1. Clone the repository:

git clone <repository-url>
cd opensearch-mcp

2. Install dependencies:

pip install -r requirements.txt

Or using uv:

uv pip install -r requirements.txt

3. Set up environment variables (optional):

cp .env.example .env
# Edit .env with your OpenSearch connection settings

Quick Start

Prerequisites: You need your own OpenSearch instance running and accessible. Configure the connection details in the .env file.

Option 1: Using Docker Compose (Recommended)

1. Copy the environment file and configure your OpenSearch connection:

cp .env.example .env
# Edit .env and set OPENSEARCH_HOST and OPENSEARCH_PORT to your OpenSearch instance

2. Start the MCP server:

docker-compose up

This will start:

• MCP server on port 48081 (HTTP endpoint: http://localhost:48081/mcp)

The MCP server will connect to your OpenSearch instance using the configuration from .env.

To run in detached mode:

docker-compose up -d

Option 2: Run MCP Server directly with Python

1. Set up environment variables:

cp .env.example .env
# Edit .env and configure OPENSEARCH_HOST and OPENSEARCH_PORT to your OpenSearch instance

2. Run the MCP server:

python server.py

The server will start on http://localhost:48081/mcp.

Option 3: Run MCP Server with Docker (standalone)

1. Build the Docker image:

docker build -t opensearch-mcp .

2. Run the container with your OpenSearch connection details:

docker run --rm -p 48081:48081 \
  -e OPENSEARCH_HOST=your-opensearch-host \
  -e OPENSEARCH_PORT=9200 \
  opensearch-mcp

Or use an env file:

docker run --rm -p 48081:48081 --env-file .env opensearch-mcp

The MCP server will be available at http://localhost:48081/mcp.

Note:

• Replace your-opensearch-host with your actual OpenSearch hostname or IP
• Use host.docker.internal (macOS/Windows) or your host IP (Linux) if OpenSearch is running on the host machine
• For remote instances, use the actual hostname or IP address

Configuration

The MCP server reads connection settings from environment variables:

Variable	Default	Description
OPENSEARCH_HOST	localhost	OpenSearch host
OPENSEARCH_PORT	9200	OpenSearch port
OPENSEARCH_USE_SSL	false	Enable SSL/TLS
OPENSEARCH_VERIFY_CERTS	false	Verify SSL certificates
OPENSEARCH_USERNAME	-	Username for authentication (optional)
OPENSEARCH_PASSWORD	-	Password for authentication (optional)

When using Docker Compose, these variables are automatically available from the container environment.

MCP Tools

stack_trace_tid

Retrieve full error stack trace by transaction ID (TID).

Parameters:

• tid (string, required): Transaction ID to search for
• index_pattern (string, optional): Index pattern to search (default: servicelogs-*)
• repo_name (string, optional): Filter by repository/application name (maps to application_name field)

Example:

{
    "tid": "e1020584c0a74074a930c4e90e953912.139.17702793574644017",
    "repo_name": "xxx"
}

Returns: Formatted text with one log entry per line. Each line follows the format:

timestamp - level - message - application_name - project

If a separate stack_trace field exists in the log document, the format is:

timestamp - level - message - stack_trace - application_name - project

Note: Log entries are sorted chronologically by @timestamp in ascending order. Newlines in messages and stack traces are normalized to | (pipe characters) for single-line format.

Example Output:

2026-02-05T08:15:57.566Z - INFO - channel GOPAY got phone A0:1ec614bbcb328b7c66436a318d7b77e0 from token - xxx - xxx
2026-02-05T08:15:57.570Z - INFO - register user for A0:44b351780fec875b97ad01d9bb946f3e , system : SYSTEM_TYPE_ATOME, channel: GOPAY - user-service-provider - pintar-user
2026-02-05T08:15:58.263Z - ERROR - POST http://:8080/user/info -d [{"module":"RESIDENTIAL_INFO","module":"RESIDENTIAL_INFO",...}] ***RESPONSE*** 400 {"timestamp":1770279358262,"status":400,"error":"Bad Request","path":"/user/info"} - xxx - xxx
2026-02-05T08:15:58.264Z - ERROR - [Gopay Linking] Failed to save user info for userId : [400 ] during [POST] to [http://:8080/user/info] [PintarUserInfoFeignClient#saveUserInfo(List)]: [{"timestamp":1770279358262,"status":400,"error":"Bad Request","path":"/user/info"}] - feign.FeignException$BadRequest: [400 ] during [POST] to [http://:8080/user/info] [PintarUserInfoFeignClient#saveUserInfo(List)]: [{"timestamp":1770279358262,"status":400,"error":"Bad Request","path":"/user/info"}] | at feign.FeignException.clientErrorStatus(FeignException.java:243) | at feign.FeignException.errorStatus(FeignException.java:223) | at feign.FeignException.errorStatus(FeignException.java:213) | ... - xxx - xxx
2026-02-05T08:15:58.267Z - INFO - [GopayServiceImpl] linking account failed for userId: , error: INVALID_KYC - xxx - xxx

Note: Log entries are sorted by timestamp in ascending order. Stack traces (when present) are included as part of the message field, with stack frames separated by | (pipe characters).

Usage with MCP Clients

The MCP server uses streamableHttp transport on port 48081. This enables HTTP-based communication instead of stdio, making it easier to deploy and scale.

Starting the Server

Important: Ensure your OpenSearch instance is running and accessible before starting the MCP server.

Option 1: Using Docker Compose (Recommended)

1. Configure your OpenSearch connection in .env:

cp .env.example .env
# Edit .env with your OpenSearch host and port

2. Start the MCP server:

docker-compose up

The MCP server will be available at http://localhost:48081/mcp.

Option 2: Running Locally

1. Set up environment variables:

cp .env.example .env
# Edit .env with your OpenSearch host and port

2. Run the MCP server:

python server.py

The server will start on http://localhost:48081/mcp.

Option 3: Using Docker Run

Build the image:

docker build -t opensearch-mcp .

Run the container with your OpenSearch connection:

docker run --rm -p 48081:48081 \
  -e OPENSEARCH_HOST=your-opensearch-host \
  -e OPENSEARCH_PORT=9200 \
  opensearch-mcp

Or use an env file:

docker run --rm -p 48081:48081 --env-file .env opensearch-mcp

Configuring MCP Clients

Cursor IDE

Add to your Cursor MCP settings (mcp.json):

{
    "mcpServers": {
        "opensearch": {
            "url": "http://localhost:48081/mcp"
        }
    }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
    "mcpServers": {
        "opensearch": {
            "url": "http://localhost:48081/mcp"
        }
    }
}

Remote Access

If the MCP server is running on a remote machine, use the remote URL:

{
    "mcpServers": {
        "opensearch": {
            "url": "http://your-server-ip:48081/mcp"
        }
    }
}

Configuration

The MCP server port and host can be configured via environment variables:

• MCP_PORT: Port for the HTTP server (default: 48081)
• MCP_HOST: Host to bind to (default: 0.0.0.0)

Example:

MCP_PORT=8080 MCP_HOST=127.0.0.1 python server.py

Docker Networking Notes

• Local development: Use http://localhost:48081/mcp
• VPN Access: The docker-compose.yml uses network_mode: host to allow the container to access VPN resources through your host's network
• Docker Compose: When using host network mode, the container shares your host's network stack, including VPN connections
• Remote access: Ensure port 48081 is accessible from your MCP client

Note: With network_mode: host, the container uses your host's network directly, so:

• VPN resources are accessible from the container
• No port mapping is needed (ports are directly accessible on the host)
• The container can access resources that require VPN connection

Development

Project Structure

opensearch-mcp/
├── src/
│   └── opensearch_mcp/
│       ├── __init__.py
│       ├── server.py              # FastMCP server with tool definitions
│       └── opensearch_client.py    # OpenSearch client wrapper
├── docker-compose.yml              # Docker Compose setup (OpenSearch + MCP server)
├── Dockerfile                      # MCP server Docker image
├── .dockerignore                   # Docker ignore file
├── .env.example                    # Example environment variables
├── mcp.json.example                # Example MCP client configuration
├── requirements.txt                # Python dependencies
├── pyproject.toml                  # Python project configuration
└── README.md                       # This file

Running Tests

# Ensure your OpenSearch instance is running and accessible

# Start MCP server with Docker Compose
docker-compose up

# Or run MCP server locally
python server.py

Docker Compose Services

The docker-compose.yml includes only the MCP server service:

1. opensearch-mcp: MCP server (uses .env file for configuration)

The MCP server service:

• Builds from the local Dockerfile
• Loads environment variables from .env file
• Connects to your OpenSearch instance using the configuration from .env
• Exposes HTTP endpoint on port 48081 at /mcp path
• Uses streamableHttp transport for MCP communication

Note: You need to provide your own OpenSearch instance. Configure the connection details in the .env file.

Log Data Format

The MCP server expects log documents with the following structure:

{
    "@timestamp": "2024-01-01T10:00:00Z",
    "level": "ERROR",
    "msg": "Error occurred...",
    "application_name": "xxx",
    "project": "xxx",
    "stack_trace": "feign.FeignException$BadRequest: [...] | at ...",
    "TID": "e1020584c0a74074a930c4e90e953912.139.17702793574644017"
}

Key fields:

• @timestamp: Log timestamp (ISO 8601 format)
• level: Log level (INFO, WARN, ERROR, etc.)
• msg: Log message content
• application_name: Application/service name (used for filtering via repo_name parameter)
• project: Project/repository name
• stack_trace: Stack trace content (optional, formatted as pipe-separated lines)
• TID: Transaction ID field (searched using phrase matching across all fields)

Troubleshooting

Connection Errors

If you see connection errors:

1. Ensure your OpenSearch instance is running and accessible
2. Check OpenSearch health: curl http://your-opensearch-host:9200/_cluster/health
3. Verify environment variables in .env are set correctly (OPENSEARCH_HOST and OPENSEARCH_PORT)
4. If running in Docker, ensure the container can reach your OpenSearch instance (network configuration)

No Results Found

• Check that your index pattern matches existing indices (default: servicelogs-*)
• Verify that the TID exists in your log documents (searched using phrase matching across all fields)
• If using repo_name filter, verify that application_name field exists and matches the filter value
• Ensure the TID format matches what's stored in your logs

SSL/TLS Issues

If using SSL:

• Set OPENSEARCH_USE_SSL=true
• Configure OPENSEARCH_VERIFY_CERTS appropriately
• Provide CA certificates if needed

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.