AI-enthusiasts/mcp-graylog

MCP Graylog Server

A Model Context Protocol (MCP) server for integrating with Graylog, enabling AI assistants to query and analyze log data for troubleshooting, debugging, monitoring, and incident response. Provides comprehensive tools for log investigation, diagnostics, observability, root cause analysis, and system health monitoring.

Quick Start

Using Docker (Recommended)

# Build and run with docker-compose
docker-compose up -d

# Or run directly with docker
docker run -d \
  --name mcp-graylog \
  -e GRAYLOG_ENDPOINT=https://your-graylog-server:9000 \
  -e GRAYLOG_USERNAME=your-username \
  -e GRAYLOG_PASSWORD=your-password \
  -p 8000:8000 \
  mcp-graylog:latest

Local Development

# Clone and setup
git clone <repository-url>
cd mcp_graylog

# Install dependencies
./install_deps.sh

# Start the server
./start.sh

Features

• Advanced Log Querying: Query Graylog logs using Elasticsearch query syntax for troubleshooting and debugging
• Stream Management: Search across multiple indices and streams for targeted investigation
• Time-based Filtering: Filter logs by time range, fields, and custom criteria for incident analysis
• Statistics & Aggregations: Retrieve log statistics and aggregations for monitoring and diagnostics
• Error Tracking: Quickly identify and analyze errors for root cause analysis
• Incident Response: Rapid log search and analysis during production incidents
• System Diagnostics: Comprehensive health checks and system monitoring tools
• Observability: Real-time log analysis and alerting capabilities
• Docker Support: Full container support with environment-based configuration
• Cursor Integration: Seamless integration with Cursor AI assistant for interactive troubleshooting
• Development Tools: Complete development toolchain with testing and linting

Table of Contents

• Installation
• Configuration
• Usage
• API Reference
• Development
• Troubleshooting
• Additional Documentation

Installation

Using Docker (Recommended)

The Docker container uses a custom entrypoint script that provides:

• Environment validation and setup
• Application configuration validation
• Proper logging and error handling
• Graceful startup process

Quick Setup

# Build the image
docker build -t mcp-graylog .

# Run with docker-compose (recommended)
docker-compose up -d

# Or run directly with docker
docker run -d \
  --name mcp-graylog \
  -e GRAYLOG_ENDPOINT=https://your-graylog-server:9000 \
  -e GRAYLOG_USERNAME=your-username \
  -e GRAYLOG_PASSWORD=your-password \
  -p 8000:8000 \
  mcp-graylog:latest

Advanced Docker Deployment

docker run -d \
  --name mcp-graylog \
  -p 8000:8000 \
  -e GRAYLOG_ENDPOINT=https://your-graylog-server:9000 \
  -e GRAYLOG_USERNAME=your-username \
  -e GRAYLOG_PASSWORD=your-password \
  -e GRAYLOG_VERIFY_SSL=true \
  -e GRAYLOG_TIMEOUT=30 \
  -e MCP_SERVER_PORT=8000 \
  -e MCP_SERVER_HOST=0.0.0.0 \
  -e LOG_LEVEL=INFO \
  -e LOG_FORMAT=json \
  --restart unless-stopped \
  mcp-graylog:latest

Local Development

1. Clone the repository:

git clone <repository-url>
cd mcp_graylog

2. Set up environment variables:

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

3. Run the server:

# Quick start with uv (recommended)
./quick_start.sh

# Or using make
make run

# Or manually with uv
uv run python -m mcp_graylog.server

# Or traditional way
python3 -m venv venv
source venv/bin/activate
pip install -e .
python -m mcp_graylog.server

Configuration

The server can be configured using environment variables:

Both username and password are required.

Usage

Available Tools

The MCP Graylog server provides the following tools for troubleshooting, debugging, and monitoring:

Core Search Tools (Troubleshooting & Investigation)

• search_logs: Search logs using Elasticsearch query syntax for debugging and incident response
• search_stream_logs: Search logs within a specific Graylog stream for targeted troubleshooting
• get_last_event_from_stream: Get the most recent event from a specific stream for monitoring and diagnostics

Stream Management Tools (Log Organization & Discovery)

• list_streams: List all available Graylog streams for monitoring setup and investigation
• search_streams_by_name: Search for streams by name or partial name for quick discovery during incidents
• get_stream_info: Get detailed information about a specific stream for diagnostics and debugging

Analysis Tools (Monitoring & Root Cause Analysis)

• get_log_statistics: Get log statistics and aggregations for pattern detection and anomaly analysis
• get_error_logs: Get error logs from the last specified time range for rapid troubleshooting
• get_log_count_by_level: Get log count aggregated by log level for health monitoring and diagnostics

System Tools (Health Checks & Diagnostics)

• get_system_info: Get Graylog system information and status for infrastructure monitoring
• test_connection: Test connection to Graylog server for connectivity troubleshooting

Example Queries

Basic Log Query

# Query logs from the last hour
{
    "query": "*",
    "time_range": "1h",
    "limit": 50
}

Stream-Specific Queries

# Get last event from 1c_eventlog stream
{
    "stream_id": "5abb3f2f7bb9fd00011595fe",
    "query": "*",
    "limit": 1
}

# Search for error messages in a specific stream
{
    "stream_id": "5abb3f2f7bb9fd00011595fe",
    "query": "level:ERROR",
    "time_range": "24h",
    "limit": 10
}

Advanced Query with Filters

# Query error logs from specific source
{
    "query": "level:ERROR AND source:web-server",
    "time_range": "24h",
    "fields": ["message", "level", "source", "timestamp"],
    "limit": 50
}

Aggregation Query

# Get error count by source
{
    "query": "level:ERROR",
    "time_range": "7d",
    "aggregation": {
        "type": "terms",
        "field": "source",
        "size": 10
    }
}

Important Note on Request Format

All API/tool requests that accept parameters (such as search_logs, search_stream_logs, get_log_statistics, etc.) must be provided as JSON objects, NOT as strings. Passing a string will result in an error.

Correct:

{
  "stream_id": "5abb3f2f7bb9fd00011595fe",
  "query": "*",
  "limit": 10
}

Incorrect:

"{stream_id:5abb3f2f7bb9fd00011595fe, query: *, limit: 10}"

Development

Available Commands

The project includes a comprehensive Makefile with the following commands:

# Development
make install          # Install the package in development mode
make test            # Run tests
make lint            # Run linting checks
make format          # Format code
make clean           # Clean build artifacts
make check           # Run all checks (format, lint, test)

# Docker
make docker-build    # Build Docker image
make docker-run      # Run Docker container
make docker-stop     # Stop Docker container
make docker-logs     # Show Docker container logs

# Testing
make test-entrypoint # Test the entrypoint configuration
make test-pydantic   # Test the Pydantic fix
make test-fixes      # Test the Pydantic and FastMCP fixes

# Setup
make install-deps    # Install dependencies using the installation script
make start           # Start the server using the startup script

# Docker Compose
make docker-compose-up    # Start services with docker-compose
make docker-compose-down  # Stop services with docker-compose
make docker-compose-logs  # Show docker-compose logs

Running Tests

# Run all tests
pytest tests/ -v

# Run specific test
pytest tests/test_client.py -v

# Run with coverage
pytest tests/ --cov=mcp_graylog

Code Quality

# Format code
black .
isort .

# Lint code
black --check .
isort --check-only .
mypy .

# Run all checks
make check

Cursor Integration

Setting up MCP Graylog Server in Cursor

The Docker container uses a custom entrypoint script that provides enhanced startup capabilities including environment validation, configuration checks, and proper logging.

Quick Setup

1. Test your setup first:

   # Run the integration test script
   python3 test_cursor_integration.py
   

2. Deploy the MCP Graylog server using Docker:

   # Build the image
   docker build -t mcp-graylog .
   
   # Run the MCP Graylog server container
   docker run -d \
     --name mcp-graylog \
     -p 8000:8000 \
           -e GRAYLOG_ENDPOINT=https://your-graylog-server:9000 \
      -e GRAYLOG_USERNAME=your-username \
      -e GRAYLOG_PASSWORD=your-password \
      -e GRAYLOG_VERIFY_SSL=true \
      -e GRAYLOG_TIMEOUT=30 \
      mcp-graylog:latest
   

3. Configure Cursor to use the MCP server:

   Open Cursor's settings and add one of the following configurations:

   **Username/Password Authentication**
   

   {
     "mcpServers": {
       "graylog": {
         "command": "docker",
         "args": [
           "run", 
           "--rm", 
           "-i", 
           "-e", "GRAYLOG_ENDPOINT=https://your-graylog-server:9000",
           "-e", "GRAYLOG_USERNAME=your-username",
           "-e", "GRAYLOG_PASSWORD=your-password",
           "-e", "GRAYLOG_VERIFY_SSL=true",
           "-e", "GRAYLOG_TIMEOUT=30",
           "mcp-graylog:latest"
         ],
         "env": {}
       }
     }
   }
   

4. Restart Cursor to load the new MCP server configuration.

Using the MCP Graylog Server in Cursor

Once configured, you can use the Graylog integration directly in Cursor's chat:

Example Queries:

Search for error logs:

Search for error logs from the last hour in Graylog

Get log statistics:

Get log count by level for the last 24 hours

Search specific streams:

List all available Graylog streams and show me the logs from the web-server stream

Complex queries:

Search for timeout errors from web-server or api-server in the last 7 days

Example Workflow in Cursor

1. Debugging Issues:

   "I'm seeing errors in my application. Can you check the Graylog logs for any ERROR level messages from the last 2 hours?"
   

2. Performance Analysis:

   "Show me the log count by level for the last 24 hours to understand the application's health"
   

3. Stream-specific Analysis:

   "List all Graylog streams and then search for any timeout errors in the web-server stream"
   

4. System Monitoring:

   "Get the Graylog system information and check if the connection is healthy"
   

Troubleshooting

Connection Issues

• Verify Graylog endpoint is accessible
• Check credentials are correct
• Ensure firewall allows connections to Graylog port

MCP Server Issues

• Check server logs: docker logs mcp-graylog
• Check entrypoint logs: docker logs mcp-graylog | grep -E "(ERROR|WARNING|Starting|Checking)"
• Test connection: Use the test_connection function
• Verify environment variables are set correctly
• Test entrypoint manually: docker run --rm mcp-graylog:latest ./entrypoint.sh

Pydantic Import Errors

• If you see PydanticImportError: BaseSettings has been moved to pydantic-settings, run: ./install_deps.sh
• Ensure pydantic-settings>=2.0.0 is installed: pip install pydantic-settings>=2.0.0
• Test the fix: make test-pydantic

FastMCP API Errors

• If you see AttributeError: 'FastMCP' object has no attribute 'function', the API has been updated to use @app.tool() instead of @app.function()
• Test the fixes: make test-fixes

Cursor Integration Issues

• Restart Cursor after configuration changes
• Check Cursor's developer console for MCP errors
• Verify the MCP server is running on the expected port
• Use the test script: python3 test_cursor_integration.py

Additional Documentation

• - Comprehensive guide with detailed examples and advanced usage
• - Usage examples and test scripts

Project Structure

mcp_graylog/
├── mcp_graylog/           # Main package
│   ├── __init__.py
│   ├── client.py          # Graylog client
│   ├── config.py          # Configuration management
│   ├── server.py          # MCP server implementation
│   └── utils.py           # Utility functions
├── tests/                 # Test suite
├── examples/              # Usage examples
├── logs/                  # Log files
├── docker-compose.yml     # Docker Compose configuration
├── Dockerfile            # Docker image definition
├── entrypoint.sh         # Docker entrypoint script
├── start.sh              # Development startup script
├── install_deps.sh       # Dependency installation script
├── Makefile              # Development commands
├── pyproject.toml        # Project metadata
├── requirements.txt       # Python dependencies
└── README.md             # This file

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes and add tests
4. Run the test suite: make test
5. Format your code: make format
6. Submit a pull request

License

MIT License - see file for details.

Support

• Issues: Report bugs and feature requests on GitHub
• Documentation: Check the
• Examples: See the for usage examples
• Testing: Use the provided test scripts to verify your setup