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
Table of Contents
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 syntaxsearch_stream_logs: Search logs within a specific Graylog streamget_last_event_from_stream: Get the most recent event from a specific stream
Stream Management Tools
list_streams: List all available Graylog streamssearch_streams_by_name: Search for streams by name or partial nameget_stream_info: Get detailed information about a specific stream
Analysis Tools
get_log_statistics: Get log statistics and aggregationsget_error_logs: Get error logs from the last specified time rangeget_log_count_by_level: Get log count aggregated by log level
System Tools
get_system_info: Get Graylog system information and statustest_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_connectionfunction - 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.0is 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