MCP Server Graylog

🚀 mcp-server-graylog

A Model Context Protocol (MCP) server for Graylog log searching. Search logs by absolute/relative timestamps, filter by streams, and debug production issues directly from Claude Desktop.

🚀 Quick Start

This MCP server allows you to search Graylog logs using exact timestamps, filter by application streams, and gain actionable insights for troubleshooting production issues. You can use it in different ways as described below.

✨ Features

• ✅ Absolute timestamp search: Debug specific errors with exact time ranges.
• ✅ Relative timestamp search: Search recent logs (last N seconds).
• ✅ Stream discovery: List all available streams/applications.
• ✅ System health check: Verify Graylog connectivity.
• ✅ Comprehensive validation: Validate ISO 8601 timestamps, query syntax, and stream IDs.
• ✅ Clear error messages: Provide actionable errors for auth, network, and API issues.
• ✅ Timeout handling: Set 30 - second timeouts to prevent hanging.
• ✅ Production - ready: Passed 54 tests with a 9.2/10 code quality score.

📦 Installation

Option 1: Use with npx (Recommended)

# No installation needed - use directly with npx
npx mcp-server-graylog

Option 2: Global Installation

npm install -g mcp-server-graylog

Option 3: Local Installation

# Clone the repository
git clone https://github.com/Pranavj17/mcp-server-graylog.git
cd mcp-server-graylog

# Install dependencies
npm install

📚 Documentation

Configuration

Claude Desktop Setup

Add the following configuration to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Using npx (Recommended)

{
  "mcpServers": {
    "graylog": {
      "command": "npx",
      "args": ["-y", "mcp-server-graylog"],
      "env": {
        "BASE_URL": "https://graylog.example.com",
        "API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Using Local Installation

{
  "mcpServers": {
    "graylog": {
      "command": "node",
      "args": ["/path/to/mcp-server-graylog/src/index.js"],
      "env": {
        "BASE_URL": "https://graylog.example.com",
        "API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Environment Variables

Getting Your Graylog API Token

1. Log in to the Graylog web interface.
2. Go to System → Users.
3. Select your user.
4. Click Edit tokens.
5. Create a new token with read permissions.
6. Copy the token value.

Available Tools

1. search_logs_absolute

Search logs using absolute timestamps (from/to). Ideal for debugging errors with specific timestamps from monitoring tools or error - tracking systems.

Parameters:

• query (required): Search query using Elasticsearch syntax.
• from (required): Start timestamp in ISO 8601 format.
• to (required): End timestamp in ISO 8601 format.
• streamId (optional): Stream ID to filter results.
• limit (optional): Maximum results (default: 50, max: 1000).

Example:

{
  "query": "\"/api/v1/registrations\" AND \"PUT\"",
  "from": "2025-10-23T10:00:00.000Z",
  "to": "2025-10-23T11:00:00.000Z",
  "streamId": "646221a5bd29672a6f0246d8",
  "limit": 100
}

2. search_logs_relative

Search logs using a relative time range (e.g., last 15 minutes). Useful for recent log analysis.

Parameters:

• query (required): Search query using Elasticsearch syntax.
• rangeSeconds (optional): Time range in seconds (default: 900 = 15 minutes, max: 86400 = 24 hours).
• streamId (optional): Stream ID to filter results.
• limit (optional): Maximum results (default: 50, max: 1000).

Example:

{
  "query": "level:ERROR",
  "rangeSeconds": 3600,
  "limit": 100
}

3. list_streams

List all available Graylog streams (applications). Use this to discover stream IDs for filtering.

Parameters: None

Returns:

{
  "total": 3,
  "streams": [
    {
      "id": "646221a5bd29672a6f0246d8",
      "title": "clientmaster",
      "description": "Client Master application logs",
      "disabled": false
    }
  ]
}

4. get_system_info

Get Graylog system information and health status. Verify connectivity and check the server version.

Parameters: None

Returns:

{
  "version": "5.1.0",
  "codename": "graylog",
  "cluster_id": "abc123",
  "is_processing": true,
  "timezone": "UTC"
}

Query Examples

Search for Errors

level:ERROR

Search for Specific Endpoint

"/api/v1/registrations" AND "PUT"

Search for HTTP Status Codes

status:500
status:>=400

Search for User Actions

user_id:12345 AND action:login

Search for Slow Requests

duration_ms:>1000

Search for Exceptions

exception:NullPointerException

Combine Multiple Conditions

level:ERROR AND source:nexus AND message:*timeout*

Search with Wildcards

message:*connection refused*

Search by Field Existence

_exists_:error_code

Common Use Cases

1. Debug Production Error

When you get an error with a timestamp from your monitoring system:

1. Copy the error timestamp from your monitoring tool.
2. Use search_logs_absolute with a ±5 - minute window.
3. Filter by the application stream.
4. Find the root cause in the logs.

2. Monitor Recent Deployments

After deploying:

1. Use search_logs_relative with the last 15 minutes.
2. Search for level:ERROR.
3. Verify no new errors are introduced.

3. Investigate API Failures

When an API endpoint fails:

1. Search for the endpoint path: "/api/v1/endpoint".
2. Filter by status codes: status:>=400.
3. Check error patterns.

Error Messages

The server provides clear, actionable error messages:

Troubleshooting

Server Won't Start

# Verify BASE_URL and API_TOKEN are set in Claude Desktop config
# Check Claude Desktop logs:
# macOS: ~/Library/Logs/Claude/mcp*.log
# Windows: %APPDATA%\Claude\logs\mcp*.log

curl -u "YOUR_API_TOKEN:token" https://graylog.example.com/api/system

Authentication Errors

• Verify the API token has read permissions in Graylog.
• Use the token value as the username and "token" as the password.
• Check if the token has expired.

No Results Returned

• Verify the stream ID is correct using the list_streams tool.
• Check if the timestamp range includes data.
• Try simplifying the query to * to see if any data exists.
• Verify the stream is not disabled.

Integration Tests Failing

# Set environment variables for integration tests
export INTEGRATION_TESTS=true
export BASE_URL=https://graylog.example.com
export API_TOKEN=your_token_here

# Run integration tests
npm run test:integration

Development

Prerequisites

• Node.js >= 18.0.0
• npm >= 8.0.0
• Access to a Graylog instance (for integration tests)

Development Workflow

# Install dependencies
npm install

# Run in development mode (auto - reload)
npm run dev

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run only unit tests
npm run test:unit

# Run integration tests (requires Graylog instance)
INTEGRATION_TESTS=true BASE_URL=https://graylog.example.com API_TOKEN=xxx npm run test:integration

# Check syntax
npm run lint

Project Structure

mcp-server-graylog/
├── src/
│   └── index.js           # Main server implementation (429 lines)
├── test/
│   ├── helpers.test.js    # Helper function tests (14 tests)
│   ├── validation.test.js # Input validation tests (24 tests)
│   ├── mcp-protocol.test.js # MCP protocol tests (16 tests)
│   └── integration.test.js  # Integration tests (7 tests)
├── example-config.json    # Claude Desktop config example
├── CONTRIBUTING.md        # Contributing guidelines
├── CHANGELOG.md          # Version history
└── package.json         # npm configuration

Running Tests

# Run all tests (54 tests)
npm test

# Expected output:
# tests 54
# pass 54
# fail 0

Architecture

Simple, focused architecture in a single file (429 lines):

• Configuration & Validation: Check environment variables.
• Helper Functions: Validate ISO 8601 timestamps and format errors.
• MCP Server Setup: Implement the standard MCP protocol.
• Tool Definitions: Define 4 tools with clear schemas.
• Tool Implementations: Provide clean, validated functions.
• Server Startup: Validate then establish a connection.

Design Principles:

• ✓ Simple and maintainable.
• ✓ One file, easy to understand.
• ✓ Clear separation of concerns.
• ✓ Comprehensive error handling.
• ✓ Input validation at boundaries.
• ✓ Consistent response format.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Quick Start:

1. Fork the repository.
2. Create a feature branch.
3. Add tests for your changes.
4. Ensure all tests pass (npm test).
5. Submit a pull request.

Changelog

See CHANGELOG.md for version history and release notes.

Security

• Use environment variables for sensitive data (never hard - code).
• Properly implement basic authentication.
• Input validation prevents injection attacks.
• Timeout prevents hanging requests.
• Error messages don't leak sensitive information.

To report security vulnerabilities, please create a private security advisory on GitHub.

📄 License

This project is under the MIT License. See the LICENSE file for details.

Links

• npm package
• GitHub repository
• Issue tracker
• Model Context Protocol
• Graylog Documentation

Acknowledgments

• Built with @modelcontextprotocol/sdk.
• Inspired by the MCP community.
• Thanks to all contributors!

Made with ❤️ for the Claude Desktop community

For questions or support, please open an issue on GitHub