rutvikraut2001/mcp-log-search

Log Search MCP Server

A Model Context Protocol (MCP) server for searching and analyzing microservice logs using natural language queries. Built with NestJS and designed to work with Claude Code and other MCP clients.

Features

• Natural Language Search: Query logs using plain English
• Multi-Service Support: Search across multiple microservices
• Request Journey Tracking: Trace requests across all services using request IDs
• Hourly Statistics: Performance analysis and peak time identification
• Status Aggregation: Count and analyze log entries by status
• Streaming Processing: Efficient handling of large gzipped log files
• Caching: 5-minute TTL caching for improved performance

System Architecture

This server is designed for microservices architectures. Default services include:

1. api-gateway: Entry point for all API requests
2. auth-service: Authentication and authorization
3. user-service: User management and profiles
4. notification-service: Email, SMS, and push notifications

You can customize the service list via the SERVICES environment variable.

Prerequisites

• Node.js >= 18.x
• npm or yarn
• Log files in gzipped JSON format (NDJSON)

Installation

# Clone the repository
git clone <repository-url>
cd log-search-mcp-server

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env and set LOG_DIRECTORY to your logs location

# Build the project
npm run build

Configuration

Environment Variables

Create a .env file:

LOG_DIRECTORY=/path/to/your/logs
SERVICES=api-gateway,auth-service,user-service,notification-service
CACHE_TTL=300
DEFAULT_SEARCH_LIMIT=100

Log File Structure

Logs should be organized as:

{LOG_DIRECTORY}/
  ├── api-gateway/
  │   └── 2025-10-30.gz
  ├── auth-service/
  │   └── 2025-10-30.gz
  ├── user-service/
  │   └── 2025-10-30.gz
  └── notification-service/
      └── 2025-10-30.gz

Each log file should contain newline-delimited JSON (NDJSON):

{"level":"INFO","message":"Request processed","timestamp":"2025-10-30T10:30:00Z","requestId":"req-123","service":"api-gateway"}

Usage with Claude Code CLI

Global Installation

# Add MCP server globally
claude mcp add --scope user --transport stdio log-search \
  --env LOG_DIRECTORY=/path/to/logs \
  -- node /path/to/dist/src/main.js

# Verify installation
claude mcp list

Example Queries

✅ "show errors in api-gateway on 2025-10-30"
✅ "find logs with user-12345"
✅ "how many requests failed today"
✅ "track request req-abc-123"
✅ "authentication errors in auth-service"
✅ "hourly stats for api-gateway"

MCP Tools

The server exposes 4 MCP tools:

1. search_logs

Search logs with natural language queries.

Parameters:

• query (required): Natural language search query
• startDate (optional): Start date (YYYY-MM-DD)
• endDate (optional): End date (YYYY-MM-DD)
• service (optional): Service name
• identifier (optional): Filter by identifier (user ID, transaction ID, etc.)
• logLevel (optional): INFO, ERROR, WARN, DEBUG
• source (optional): Source system name
• limit (optional): Max results (default: 10, max: 100)

2. get_log_summary

Get statistical summary of logs.

Parameters:

• startDate (required): Start date
• endDate (required): End date
• service (required): Service name

3. track_request_journey

Track a request across all services.

Parameters:

• requestId (required): Request ID to track
• startDate (optional): Start date

4. get_hourly_stats

Get hourly breakdown of log statistics.

Parameters:

• date (required): Date (YYYY-MM-DD)
• service (required): Service name

Development

# Run tests
npm test

# Run tests with coverage
npm test -- --coverage

# Run tests in watch mode
npm test -- --watch

# Build with watch mode
npm run build -- --watch

Testing

Generate Test Logs

./scripts/setup-test-logs.sh

This creates a test-logs/ directory with sample gzipped JSON logs for testing.

Customization

Adding Custom Services

1. Set the SERVICES environment variable:

   SERVICES=order-service,payment-service,inventory-service
   

2. Create corresponding directories in your LOG_DIRECTORY

3. The server will automatically detect and search these services

Log Format Requirements

• Required fields: level, message
• Optional but recommended: timestamp (or @timestamp), requestId, service
• Format: Newline-delimited JSON (NDJSON), gzipped

Performance

• Streaming: Line-by-line processing (no full-file loading)
• Caching: 5-minute TTL on search results
• Early Termination: Stops when limit is reached
• Default Limits: 500k lines max to prevent timeouts

Troubleshooting

"No MCP servers configured"

Run from within the project directory or add with --scope user flag.

"LOG_DIRECTORY not found"

Ensure the path in .env is absolute and readable.

"Service type is required"

Either specify service in the query or use keywords like "gateway", "auth", etc.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: npm test
5. Submit a pull request

License

ISC

Author

Rutvik Raut