MCP Graylog Server
This server lets AI assistants query and analyze Graylog logs via MCP tools.
Search log messages with query strings, relative/absolute/keyword time ranges, stream filters, field selection, limit, and offset.
Search logs within a specific stream by providing a stream ID.
Run aggregations on log data, including count, average, sum, min, max, percentile, and other metrics, grouped by a field.
List all available Graylog streams.
Get details about a specific stream by ID.
Find streams by name.
Retrieve Graylog system information.
Quickly fetch recent error/critical logs with configurable hours and limit.
Count logs grouped by log level for recent time windows.
Enables integration with Graylog to query and analyze log data, providing tools for stream management, time-based filtering, and log statistics or aggregations.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCP Graylog Servershow me the error logs from the production stream for the last hour"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP Graylog
MCP Graylog is a Model Context Protocol server for querying Graylog 6+ from AI assistants. The default transport is Codex stdio. Streamable HTTP is available only when you explicitly opt in for a remote, shared, or containerized runtime. The server uses MCP Python SDK 2.x and supports its current and legacy protocol revisions.
Install Dependencies
Use Python 3.11 or newer. If you are new to Python projects, the safest setup is to keep this server in its own virtual environment.
Install Python 3.11+ and
uv.On macOS with Homebrew:
brew install python@3.11 uvIf Python is already installed, you can install
uvwith pip:python3 -m pip install --user uvCreate and activate a virtual environment from the repository root:
uv venv venv --python 3.11 source venv/bin/activateInstall the server dependencies:
uv pip install -e .For development, tests, linting, and type checks, install the dev extras:
uv pip install -e ".[dev]"Check that the command is available:
uv run mcp-graylog --helpIf you installed the dev extras, run the test suite:
uv run pytest -q
Related MCP server: Graylog MCP Server
Quick Start: Codex Stdio
Install the project dependencies, then add this server to your Codex config:
[mcp_servers.graylog]
command = "uv"
args = ["run", "mcp-graylog"]
[mcp_servers.graylog.env]
GRAYLOG_ENDPOINT = "https://graylog.example.com"
GRAYLOG_TOKEN = "gl2-your-token"
MCP_SERVER_TRANSPORT = "stdio"Run the command from this repository when Codex starts the MCP server:
uv run mcp-graylogToken authentication with GRAYLOG_TOKEN is preferred. Legacy basic
credentials are still supported by the runtime for older installations, but new
setups should use a Graylog access token.
MCP Client Configuration Examples
All local client examples use stdio. Run them from this repository checkout, or
replace uv with an absolute command that can start mcp-graylog in your
environment.
Codex
Add this to ~/.codex/config.toml:
[mcp_servers.graylog]
command = "uv"
args = ["run", "mcp-graylog"]
[mcp_servers.graylog.env]
GRAYLOG_ENDPOINT = "https://graylog.example.com"
GRAYLOG_TOKEN = "gl2-your-token"
MCP_SERVER_TRANSPORT = "stdio"Claude Code
For a project-shared server, add .mcp.json at the repository root:
{
"mcpServers": {
"graylog": {
"type": "stdio",
"command": "uv",
"args": ["run", "mcp-graylog"],
"env": {
"GRAYLOG_ENDPOINT": "https://graylog.example.com",
"GRAYLOG_TOKEN": "gl2-your-token",
"MCP_SERVER_TRANSPORT": "stdio"
}
}
}
}Equivalent CLI setup:
claude mcp add-json graylog '{"type":"stdio","command":"uv","args":["run","mcp-graylog"],"env":{"GRAYLOG_ENDPOINT":"https://graylog.example.com","GRAYLOG_TOKEN":"gl2-your-token","MCP_SERVER_TRANSPORT":"stdio"}}'Cursor
Add .cursor/mcp.json in the project, or ~/.cursor/mcp.json globally:
{
"mcpServers": {
"graylog": {
"type": "stdio",
"command": "uv",
"args": ["run", "mcp-graylog"],
"env": {
"GRAYLOG_ENDPOINT": "https://graylog.example.com",
"GRAYLOG_TOKEN": "gl2-your-token",
"MCP_SERVER_TRANSPORT": "stdio"
}
}
}
}OpenCode
Add this to opencode.jsonc:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"graylog": {
"type": "local",
"command": ["uv", "run", "mcp-graylog"],
"environment": {
"GRAYLOG_ENDPOINT": "https://graylog.example.com",
"GRAYLOG_TOKEN": "gl2-your-token",
"MCP_SERVER_TRANSPORT": "stdio"
},
"enabled": true
}
}
}Hermes
Add this to ~/.hermes/config.yaml:
mcp_servers:
graylog:
command: "uv"
args: ["run", "mcp-graylog"]
env:
GRAYLOG_ENDPOINT: "https://graylog.example.com"
GRAYLOG_TOKEN: "gl2-your-token"
MCP_SERVER_TRANSPORT: "stdio"Run /reload-mcp in Hermes after changing the file.
OpenClaw
Add this to ~/.openclaw/openclaw.json under mcp.servers, or use
openclaw mcp set graylog '<json>' with the same server object:
{
"mcp": {
"servers": {
"graylog": {
"command": "uv",
"args": ["run", "mcp-graylog"],
"env": {
"GRAYLOG_ENDPOINT": "https://graylog.example.com",
"GRAYLOG_TOKEN": "gl2-your-token",
"MCP_SERVER_TRANSPORT": "stdio"
}
}
}
}
}Streamable HTTP
Use Streamable HTTP only when the server must be reachable from another process or host:
GRAYLOG_ENDPOINT="https://graylog.example.com" \
GRAYLOG_TOKEN="gl2-your-token" \
MCP_SERVER_ALLOWED_HOSTS="mcp.example.com,mcp.example.com:*" \
uv run mcp-graylog --transport streamable-http --host 0.0.0.0 --port 8000 --path /mcpThe equivalent environment setting is:
MCP_SERVER_TRANSPORT=streamable-http
MCP_SERVER_HOST=0.0.0.0
MCP_SERVER_PORT=8000
MCP_SERVER_PATH=/mcp
MCP_SERVER_DNS_REBINDING_PROTECTION=true
MCP_SERVER_ALLOWED_HOSTS=mcp.example.com,mcp.example.com:*
MCP_SERVER_ALLOWED_ORIGINS=https://app.example.comMCP_SERVER_ALLOWED_HOSTS contains the exact hostnames accepted by the HTTP
transport. Add both the bare hostname and hostname:* when clients may use an
explicit port. For a direct IP deployment, use a value such as
192.0.2.10:*. Configure MCP_SERVER_ALLOWED_ORIGINS only for browser clients.
To accept requests for any host behind a trusted reverse proxy, set
MCP_SERVER_DNS_REBINDING_PROTECTION=false. This disables both Host and Origin
validation and should not be used when the server is exposed directly.
Configuration
Variable | Required | Default | Description |
| yes | - | Base URL for Graylog, without embedded credentials. |
| yes for new setups | - | Preferred Graylog access token. |
| no |
| Verify TLS certificates. |
| no |
| Graylog HTTP timeout in seconds. |
| no |
|
|
| no |
| Streamable HTTP bind host. |
| no |
| Streamable HTTP bind port. |
| no |
| Streamable HTTP MCP path. |
| no |
| Validate HTTP Host and Origin headers. |
| no | localhost values | Comma-separated allowed Host values. |
| no | localhost values | Comma-separated allowed browser origins. |
| no |
| Server log level. |
Graylog 6+ API Compatibility
The server uses the current Graylog Search Scripting and system APIs:
POST /api/search/messagesPOST /api/search/aggregateGET /api/streamsGET /api/streams/{stream_id}GET /api/system
It does not use the legacy universal search API. Search payloads use query,
timerange, streams, fields, size, and from.
MCP Tools
search_logs(search)searches messages with a typedMessageSearchInput.search_stream_logs(stream_id, search)searches messages in one stream.aggregate_logs(aggregation)runs grouped aggregations withAggregateLogsInput.list_streams()returns available Graylog streams.get_stream_info(stream_id)returns one stream definition.search_streams_by_name(stream_name)filters streams locally by title.get_system_info()returns Graylog system information.get_error_logs(hours=1, limit=100)searches recent error and critical logs.get_log_count_by_level(hours=1)aggregates recent logs bylevel.
Tool Input Examples
{
"query": "level:ERROR",
"timerange": {"value": 1, "unit": "h"},
"streams": [],
"fields": ["timestamp", "source", "level", "message"],
"limit": 50,
"offset": 0
}{
"query": "*",
"timerange": {"keyword": "Last 24 hours"},
"field": "source",
"metric": "count",
"limit": 10
}{
"stream_id": "000000000000000000000001",
"search": {
"query": "source:api",
"timerange": {"value": 24, "unit": "h"},
"fields": ["timestamp", "source", "message"],
"limit": 25,
"offset": 0
}
}Development
uv sync --extra dev
uv run pytest
uv run ruff check .The package entrypoint is mcp-graylog, provided by mcp_graylog.cli:main.
Available Tools
9 toolsaggregate_logsD
| Name | Required | Description | Default |
|---|---|---|---|
| aggregation | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_error_logsD
| Name | Required | Description | Default |
|---|---|---|---|
| hours | No | ||
| limit | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_log_count_by_levelD
| Name | Required | Description | Default |
|---|---|---|---|
| hours | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_stream_infoD
| Name | Required | Description | Default |
|---|---|---|---|
| stream_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_system_infoD
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_streamsD
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_logsD
| Name | Required | Description | Default |
|---|---|---|---|
| search | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_stream_logsD
| Name | Required | Description | Default |
|---|---|---|---|
| search | Yes | ||
| stream_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_streams_by_nameD
| Name | Required | Description | Default |
|---|---|---|---|
| stream_name | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
9 tool updates
v0.2.0- First observed
aggregate_logs - First observed
get_error_logs - First observed
get_log_count_by_level - First observed
get_stream_info - First observed
get_system_info - First observed
list_streams - First observed
search_logs - First observed
search_stream_logs - First observed
search_streams_by_name
TDQS
Scored across 9 tools
Some tools have overlapping functionality, such as search_logs and search_stream_logs, or aggregate_logs and get_log_count_by_level, which could cause confusion. However, most tools target distinct resources or actions.
Tools follow a snake_case pattern with verbs like get, list, search, aggregate. The pattern is mostly consistent but not perfectly uniform, e.g., list_streams vs get_stream_info.
9 tools is appropriate for a Graylog server, covering the main read operations without being excessive. It feels well-scoped.
The set covers common query and retrieval operations but lacks write or management tools (e.g., create stream, update). It seems focused on read-only access, which may be intentional but is incomplete for full lifecycle.
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Search log events, investigate anomalies, and manage cases in your Knowledge Grid tenant.
1Query your Twitch streams, events, supporters, raids & rankings from an AI assistant via OAuth.
Read-only access to Auralogs production logs: search logs, inspect errors, review AI analyses.
Query application logs, traces, and metrics from your AI coding assistant via Foam's MCP server.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to query and analyze logs from Graylog instances using universal search with relative or absolute time windows, supporting both full result retrieval and lightweight count-only queries.201MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to search and analyze logs in Graylog using three powerful tools: generic log search with Lucene queries, smart UUID/trace ID lookup across multiple fields, and stream-specific message retrieval with automatic field normalization.13MIT
- AlicenseAqualityCmaintenanceEnables querying Graylog log management system for messages using natural language, supporting multiple instances and flexible search parameters.1389MIT
- AlicenseAqualityDmaintenanceAn MCP server that gives AI assistants direct access to your Graylog logs -- search, aggregate, analyze, and cluster log data through natural language.2327MIT