MCP Graylog Server

A Model Context Protocol (MCP) server for integrating with Graylog, enabling AI assistants to query and analyze log data.

Quick Start

Using Docker (Recommended)

Local Development

Features

• Advanced Log Querying: Query Graylog logs using Elasticsearch query syntax

• Stream Management: Search across multiple indices and streams

• Time-based Filtering: Filter logs by time range, fields, and custom criteria

• Statistics & Aggregations: Retrieve log statistics and aggregations

• Docker Support: Full container support with environment-based configuration

• Cursor Integration: Seamless integration with Cursor AI assistant

• Health Monitoring: Built-in health checks and system monitoring

• Error Handling: Comprehensive error handling and logging

• 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

Advanced Docker Deployment

Local Development

1. Clone the repository:

2. Install dependencies:

3. Set up environment variables:

4. Run the 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:

Core Search Tools

• search_logs: Search logs using Elasticsearch query syntax

• search_stream_logs: Search logs within a specific Graylog stream

• get_last_event_from_stream: Get the most recent event from a specific stream

Stream Management Tools

• list_streams: List all available Graylog streams

• search_streams_by_name: Search for streams by name or partial name

• get_stream_info: Get detailed information about a specific stream

Analysis Tools

• get_log_statistics: Get log statistics and aggregations

• get_error_logs: Get error logs from the last specified time range

• get_log_count_by_level: Get log count aggregated by log level

System Tools

• get_system_info: Get Graylog system information and status

• test_connection: Test connection to Graylog server

Example Queries

Basic Log Query

Stream-Specific Queries

Advanced Query with Filters

Aggregation Query

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:

Incorrect:

Development

Available Commands

The project includes a comprehensive Makefile with the following commands:

Running Tests

Code Quality

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:

Get log statistics:

Search specific streams:

Complex queries:

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

• Complete Documentation - Comprehensive guide with detailed examples and advanced usage

• Examples - Usage examples and test scripts

Project Structure

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 LICENSE file for details.

Support

• Issues: Report bugs and feature requests on GitHub

• Documentation: Check the complete documentation

• Examples: See the examples directory for usage examples

• Testing: Use the provided test scripts to verify your setup