Skip to content

DOCUMENTATION.md

Latest commit

 

History

History
executable file
·
420 lines (314 loc) · 9.81 KB

DOCUMENTATION.md

File metadata and controls

executable file
·
420 lines (314 loc) · 9.81 KB

MCP Graylog Server Documentation

Overview

The MCP Graylog Server provides a Model Context Protocol (MCP) interface to Graylog, enabling AI assistants to query logs, analyze data, and manage streams through a standardized API.

Features

  • Log Search: Search logs using Elasticsearch query syntax
  • Stream Management: List and search Graylog streams
  • Analytics: Get log statistics and aggregations
  • System Info: Retrieve Graylog system information
  • Connection Testing: Test connectivity to Graylog server

Installation

Prerequisites

  • Python 3.8+
  • Graylog server with REST API access
  • Graylog username and password

Quick Start

  1. Clone the repository:

    git clone <repository-url>
cd mcp_graylog

  2. Install dependencies:

    pip install -r requirements.txt

  3. Configure environment variables:

    cp env.example .env
# Edit .env with your Graylog credentials

  4. Run the server:

    python run_server.py

Configuration

Environment Variables

Variable Description Required Default
GRAYLOG_ENDPOINT Graylog server URL Yes -
GRAYLOG_USERNAME Graylog username Yes -
GRAYLOG_PASSWORD Graylog password Yes -
GRAYLOG_VERIFY_SSL Verify SSL certificates No true
GRAYLOG_TIMEOUT Request timeout (seconds) No 30
MCP_SERVER_PORT MCP server port No 8000
MCP_SERVER_HOST MCP server host No 0.0.0.0
LOG_LEVEL Logging level No INFO
LOG_FORMAT Log format (json/text) No json

Both username and password are required.

API Reference

Request Format Validation

The MCP server now includes comprehensive request validation to ensure all requests conform to Graylog API specifications:

Time Range Format

  • Relative ranges: 1h, 24h, 7d, 30m, 1w
  • Absolute ranges: ISO 8601 format (e.g., 2024-01-01T00:00:00Z)

Query Validation

  • Queries cannot be empty
  • Must be valid Elasticsearch syntax
  • Proper escaping for special characters

Parameter Bounds

  • limit: 1-1000 for search queries
  • size: 1-100 for aggregations
  • offset: Non-negative integers

Core Search Functions

search_logs

Search logs using Elasticsearch query syntax.

Warning: Request must be a JSON object, not a string.

Parameters:

  • query (string, required): Search query (Elasticsearch syntax)
  • time_range (string, optional): Time range (e.g., '1h', '24h', '7d'). Defaults to '1h'
  • fields (array, optional): Fields to return
  • limit (integer, optional): Maximum number of results (1-1000, default: 50)
  • offset (integer, optional): Result offset (default: 0)
  • sort (string, optional): Sort field
  • sort_direction (string, optional): Sort direction ('asc' or 'desc', default: 'desc')
  • stream_id (string, optional): Stream ID to search in

Example:

{
    "query": "level:ERROR AND source:web-server",
    "time_range": "24h",
    "fields": ["message", "level", "source", "timestamp"],
    "limit": 100,
    "sort": "timestamp",
    "sort_direction": "desc"
}

search_stream_logs

Search logs within a specific Graylog stream.

Warning: Request must be a JSON object, not a string.

Parameters:

  • stream_id (string, required): Stream ID to search in
  • query (string, required): Search query
  • time_range (string, optional): Time range (default: '1h')
  • fields (array, optional): Fields to return
  • limit (integer, optional): Maximum number of results (1-100, default: 50)

Example:

{
    "stream_id": "5abb3f2f7bb9fd00011595fe",
    "query": "level:ERROR",
    "time_range": "7d",
    "fields": ["message", "level", "source"],
    "limit": 50
}

Analytics Functions

get_log_statistics

Get log statistics and aggregations from Graylog.

Warning: Request must be a JSON object, not a string.

Parameters:

  • query (string, required): Search query
  • time_range (string, required): Time range
  • aggregation_type (string, required): Aggregation type
  • field (string, required): Field to aggregate on
  • size (integer, optional): Number of buckets (1-100, default: 10)
  • interval (string, optional): Time interval for date histograms

Valid aggregation types:

  • terms: Count occurrences of field values
  • date_histogram: Time-based aggregations
  • cardinality: Count unique values
  • stats: Statistical aggregations
  • min, max, avg, sum: Mathematical aggregations

Example:

{
    "query": "level:ERROR",
    "time_range": "7d",
    "aggregation_type": "terms",
    "field": "source",
    "size": 10
}

Stream Management Functions

list_streams

List all available Graylog streams.

Returns: JSON string containing list of streams with their IDs and metadata.

search_streams_by_name

Search for Graylog streams by name or partial name.

Parameters:

  • stream_name (string, required): Partial or full stream name to search for

Example:

search_streams_by_name("1c_eventlog")

get_stream_info

Get detailed information about a specific Graylog stream.

Parameters:

  • stream_id (string, required): The ID of the stream to get information for

Example:

get_stream_info("5abb3f2f7bb9fd00011595fe")

Analysis Functions

get_error_logs

Get error logs from the last specified time range.

Parameters:

  • time_range (string, optional): Time range to search (default: '1h')
  • limit (integer, optional): Maximum number of results (1-1000, default: 100)

Example:

{
    "time_range": "24h",
    "limit": 50
}

get_log_count_by_level

Get log count aggregated by log level.

Parameters:

  • time_range (string, optional): Time range to analyze (default: '1h')

Example:

{
    "time_range": "24h"
}

System Functions

get_system_info

Get Graylog system information and status.

Returns: JSON string containing system information.

test_connection

Test connection to Graylog server.

Returns: JSON string indicating connection status.

get_last_event_from_stream

Get the last event from a specific Graylog stream.

Parameters:

  • stream_id (string, required): The ID of the stream to get the last event from
  • time_range (string, optional): Time range to search in (default: '1h')

Example:

{
    "stream_id": "5abb3f2f7bb9fd00011595fe",
    "time_range": "1h"
}

Graylog API Compatibility

Request Format

The MCP server ensures all requests conform to Graylog API specifications:

Search Endpoints

  • Endpoint: /api/search/universal/relative
  • Method: GET
  • Parameters: Query parameters for filtering and pagination

Aggregation Endpoints

  • Endpoint: /api/search/universal/relative/{aggregation_type}
  • Method: POST
  • Body: JSON with query, range, field, and aggregation parameters

Time Range Handling

  • Relative ranges: Converted to seconds (e.g., 1h → 3600)
  • Absolute ranges: ISO 8601 format preserved
  • Validation: Ensures proper format before sending to Graylog

Error Handling

The server provides comprehensive error handling:

  • Validation errors: Clear messages for invalid parameters
  • Authentication errors: Specific handling for 401 responses
  • Connection errors: Graceful handling of network issues
  • Graylog API errors: Proper error propagation from Graylog

Best Practices

1. Security

Use Username/Password Authentication

export GRAYLOG_USERNAME="your-username"
export GRAYLOG_PASSWORD="your-password"

Enable SSL Verification

export GRAYLOG_VERIFY_SSL="true"

2. Performance

Optimize Query Limits

  • Use appropriate limit values (1-1000)
  • Implement pagination with offset
  • Filter results with specific fields

Efficient Time Ranges

  • Use relative ranges for recent data (1h, 24h)
  • Use absolute ranges for historical analysis
  • Avoid overly broad time ranges

3. Query Optimization

Use Specific Queries

# Good: Specific query
{"query": "level:ERROR AND source:web-server"}

# Avoid: Too broad
{"query": "*"}

Leverage Fields Filtering

{
    "query": "level:ERROR",
    "fields": ["message", "level", "source", "timestamp"]
}

4. Error Handling

Check Connection Status

# Test connection before making queries
test_connection()

Handle Validation Errors

# All functions return JSON with error details
result = search_logs(request)
if "error" in result:
    print(f"Error: {result['error']}")

Troubleshooting

Common Issues

Authentication Errors

Error: Authentication failed (401)

Solution: Verify username and password in environment variables.

Connection Errors

Error: Connection test failed

Solution: Check Graylog server URL and network connectivity.

Validation Errors

Error: Invalid time range format

Solution: Use supported formats: relative (1h, 24h) or ISO 8601.

Query Errors

Error: Query parameter is required

Solution: Ensure query is not empty and uses valid Elasticsearch syntax.

Debug Mode

Enable debug logging for detailed request/response information:

export LOG_LEVEL="DEBUG"

Health Check

Use the health check endpoint to verify server status:

curl http://localhost:8000/health_check

Development

Running Tests

pytest tests/

Code Quality

# Run linting
flake8 mcp_graylog/

# Run type checking
mypy mcp_graylog/

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests for new functionality
  5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.