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)

# 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
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

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

Clone the repository:

git clone <repository-url>
cd mcp_graylog

Install dependencies:

# Using the installation script (recommended)
./install_deps.sh

# Or install manually
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install -e .

Set up environment variables:

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

Run the server:

# Using the startup script (recommended)
./start.sh

# Or run directly
python -m mcp_graylog.server

Configuration

The server can be configured using 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.

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

# 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

Test your setup first:

# Run the integration test script
python3 test_cursor_integration.py

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

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": {}
    }
  }
}

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

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?"

Performance Analysis:

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

Stream-specific Analysis:

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

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

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

Fork the repository
Create a feature branch: git checkout -b feature-name
Make your changes and add tests
Run the test suite: make test
Format your code: make format
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

Name		Name	Last commit message	Last commit date
Latest commit History 17 Commits
.cursor/rules		.cursor/rules
examples		examples
mcp_graylog		mcp_graylog
tests		tests
.gitignore		.gitignore
DOCUMENTATION.md		DOCUMENTATION.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
docker-compose.yml		docker-compose.yml
entrypoint.sh		entrypoint.sh
env.example		env.example
example_setup.sh		example_setup.sh
install_deps.sh		install_deps.sh
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
run_server.py		run_server.py
start.sh		start.sh
test_cursor_integration.py		test_cursor_integration.py
test_entrypoint.sh		test_entrypoint.sh
test_fixes.py		test_fixes.py
test_pydantic_fix.py		test_pydantic_fix.py

License

mothlike/mcp_graylog

Folders and files

Latest commit

History

Repository files navigation

MCP Graylog Server

Quick Start

Using Docker (Recommended)

Local Development

Features

Table of Contents

Installation

Using Docker (Recommended)

Quick Setup

Advanced Docker Deployment

Local Development

Configuration

Usage

Available Tools

Core Search Tools

Stream Management Tools

Analysis Tools

System Tools

Example Queries

Basic Log Query

Stream-Specific Queries

Advanced Query with Filters

Aggregation Query

Important Note on Request Format

Development

Available Commands

Running Tests

Code Quality

Cursor Integration

Setting up MCP Graylog Server in Cursor

Quick Setup

Using the MCP Graylog Server in Cursor

Example Queries:

Example Workflow in Cursor

Troubleshooting

Connection Issues

MCP Server Issues

Pydantic Import Errors

FastMCP API Errors

Cursor Integration Issues

Additional Documentation

Project Structure

Contributing

License

Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Languages

Packages