graylog-mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Leo Ruellas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+# Graylog MCP Server
+
+A minimal MCP (Model Context Protocol) server in JavaScript that integrates with Graylog.
+
+## Features
+
+- JavaScript MCP server
+- Tools: `fetch_graylog_messages` (query Graylog and return messages)
+
+## Requirements
+
+- Node.js 18+
+
+## Installation
+
+```bash
+git clone git@github.com:lcaliani/graylog-mcp.git
+cd graylog-mcp
+npm install
+```
+
+## Configuration
+
+Set the following environment variables so the server can connect to Graylog:
+
+- `BASE_URL`: Graylog base URL, e.g. `https://graylog.example.com`
+- `API_TOKEN`: Graylog API token (used as the username, with password `token`)
+
+> :exclamation: Suggestion: add these variables to your respective MCP client configuration file or app. Example in **Cursor** more below.
+
+
+## Use with an MCP client (Cursor/Claude Desktop)
+
+1. Add this server to your MCP client configuration, poiting to the mcp entrypoint file (`src/index.js`). Common locations:
+
+- Cursor: `~/.cursor/mcp.json`
+- Claude Desktop (macOS): `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Claude Desktop (Linux): `~/.config/claude-desktop/claude_desktop_config.json`
+
+Example config in **Cursor**:
+
+```json
+{
+  "mcpServers": {
+    "simple-graylog-mcp": {
+      "command": "node",
+      "args": [
+        "/path/to/graylog-mcp/src/index.js"
+      ],
+      "env": {
+        "BASE_URL": "http://your.graylog.server.net.br:9000",
+        "API_TOKEN": "your_graylog_api_token"
+      }
+    }
+  }
+}
+```
+
+2. After that, your client is already able to use the `fetch_graylog_messages` tool. Example prompt:
+
+```
+Search for the latest 20 error logs of the example application, given that they occurred in the last 15 minutes.
+```
+
+This should be enough for the tool to be used, but if wanted, you can also explicitly "force" the use of the tool. Example prompt:
+
+```
+Search for the latest 20 error logs of the example application, given that they occurred in the last 15 minutes.
+
+use simple-graylog-mcp
+```
+
+
+## Available tools
+
+### fetch_graylog_messages
+
+Fetch messages from Graylog.
+
+Parameters:
+
+- `query` (string): Search query. Example: `level:ERROR AND service:api`.
+- `searchTimeRangeInSeconds` (number, optional): Relative time range in seconds. Default: `900` (15 minutes).
+- `searchCountLimit` (number, optional): Max number of messages. Default: `50`.
+- `fields` (string, optional): Comma-separated fields to include. Default: `*`.
+
+## Troubleshooting
+
+- Ensure `BASE_URL` and `API_TOKEN` are set.
+- Verify Node.js version is 18+.
+- Run `npm install` if dependencies are missing.
+
+## License
+
+MIT

package/example-config.json

@@ -0,0 +1,14 @@
+{
+    "mcpServers": {
+        "simple-graylog-mcp": {
+            "command": "node",
+            "args": [
+              "/path/to/graylog-mcp/src/index.js"
+            ],
+            "env": {
+              "BASE_URL": "http://graylog1.internal.net.br:9000",
+              "API_TOKEN": "YOUR_GRAYLOG_API_TOKEN_HERE"
+            }
+          }
+    }
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+    "name": "graylog-mcp-server",
+    "version": "1.0.0",
+    "description": "MCP server for fetching data from Graylog",
+    "main": "src/index.js",
+    "type": "module",
+    "scripts": {
+        "start": "node src/index.js",
+        "dev": "node --watch src/index.js",
+        "test": "node test-server.js",
+        "test:manual": "echo \"Error: no test specified\" && exit 1"
+    },
+    "keywords": [
+        "mcp",
+        "graylog",
+        "logging",
+        "model-context-protocol"
+    ],
+    "author": "Leo Ruellas",
+    "license": "MIT",
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "^1.18.0",
+        "axios": "^1.12.2",
+        "npm": "^11.6.0",
+        "zod": "^3.25.76"
+    },
+    "devDependencies": {
+        "@types/node": "^20.19.15",
+        "typescript": "^5.9.2"
+    },
+    "engines": {
+        "node": ">=18.0.0"
+    }
+}

package/src/config.js

@@ -0,0 +1,47 @@
+import { readFileSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+
+let connections = {};
+const configPath = join(homedir(), ".graylog-mcp", "config.json");
+try {
+    const config = JSON.parse(readFileSync(configPath, "utf-8"));
+    connections = config.connections || {};
+} catch {
+    // No config file found
+}
+
+let activeConnection = null;
+
+export const DEFAULT_FIELDS = [
+    "timestamp",
+    "gl2_message_id",
+    "source",
+    "env",
+    "level",
+    "message",
+    "logger_name",
+    "thread_name",
+    "PODNAME",
+];
+
+export function getConfigPath() {
+    return configPath;
+}
+
+export function getConnections() {
+    return connections;
+}
+
+export function getActiveConnection() {
+    return activeConnection;
+}
+
+export function setActiveConnection(name) {
+    activeConnection = name;
+}
+
+export function getActiveConnectionConfig() {
+    if (!activeConnection) return null;
+    return connections[activeConnection];
+}

package/src/index.js

@@ -0,0 +1,329 @@
+#!/usr/bin/env node
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+    CallToolRequestSchema,
+    ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+import {
+    getConfigPath, getConnections, getActiveConnection,
+    setActiveConnection, getActiveConnectionConfig, DEFAULT_FIELDS
+} from "./config.js";
+import { buildQueryString, resolveFields, extractMessages, fetchMessageById, fetchStreams, searchGraylog } from "./query.js";
+import { toolDefinitions } from "./tools.js";
+
+const server = new Server({
+    name: "simple-graylog-mcp",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return { tools: toolDefinitions };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name } = request.params;
+
+    if (name === "list_connections") {
+        return listConnections();
+    }
+    if (name === "use_connection") {
+        return useConnection(request);
+    }
+    if (name === "fetch_graylog_messages") {
+        return fetchGraylogMessages(request);
+    }
+    if (name === "get_surrounding_messages") {
+        return getSurroundingMessages(request);
+    }
+    if (name === "list_streams") {
+        return listStreams();
+    }
+    if (name === "list_field_values") {
+        return listFieldValues(request);
+    }
+
+    throw new Error(`Tool not found: ${name}`);
+});
+
+function listConnections() {
+    const connections = getConnections();
+    const names = Object.keys(connections);
+    if (names.length === 0) {
+        return {
+            content: [{
+                type: "text",
+                text: `No connections found. Add connections to ${getConfigPath()}`,
+            }],
+        };
+    }
+
+    const active = getActiveConnection();
+    const list = names.map(n => {
+        return `${active === n ? "* " : "  "}${n} (${connections[n].baseUrl})`;
+    }).join("\n");
+
+    return {
+        content: [{
+            type: "text",
+            text: `Available connections (* = active):\n${list}`,
+        }],
+    };
+}
+
+function useConnection(request) {
+    const connectionName = request.params.arguments?.name;
+    if (!connectionName) {
+        throw new Error("Connection name is required");
+    }
+
+    const connections = getConnections();
+    if (!connections[connectionName]) {
+        const available = Object.keys(connections).join(", ");
+        return {
+            content: [{
+                type: "text",
+                text: `Connection "${connectionName}" not found. Available: ${available || "none"}`,
+            }],
+        };
+    }
+
+    setActiveConnection(connectionName);
+    return {
+        content: [{
+            type: "text",
+            text: `Connected to "${connectionName}" (${connections[connectionName].baseUrl})`,
+        }],
+    };
+}
+
+function requireActiveConnection() {
+    const conn = getActiveConnectionConfig();
+    if (!conn) {
+        const available = Object.keys(getConnections()).join(", ");
+        return {
+            error: {
+                content: [{
+                    type: "text",
+                    text: `No active connection. Use 'use_connection' first. Available: ${available || "none"}`,
+                }],
+            },
+        };
+    }
+    return { conn };
+}
+
+async function fetchGraylogMessages(request) {
+    const { conn, error } = requireActiveConnection();
+    if (error) return error;
+
+    const args = request.params.arguments || {};
+    const queryString = buildQueryString(args.query, args.filters, args.exactMatch ?? true);
+    const fieldList = resolveFields(args.fields, DEFAULT_FIELDS);
+    const pageSize = args.pageSize ?? 50;
+    const page = args.page ?? 1;
+    const offset = (page - 1) * pageSize;
+
+    const payload = {
+        queries: [{
+            id: "q1",
+            query: { type: "elasticsearch", query_string: queryString },
+            timerange: { type: "relative", range: args.searchTimeRangeInSeconds ?? 900 },
+            search_types: [{
+                id: "st1",
+                type: "messages",
+                limit: pageSize,
+                offset,
+            }]
+        }]
+    };
+
+    try {
+        const data = await searchGraylog(conn.baseUrl, conn.apiToken, payload);
+        const { totalResults, extracted } = extractMessages(data, fieldList);
+        const totalPages = Math.ceil(totalResults / pageSize);
+
+        return {
+            content: [{
+                type: "text",
+                text: JSON.stringify({
+                    total_results: totalResults,
+                    page,
+                    page_size: pageSize,
+                    total_pages: totalPages,
+                    messages: extracted,
+                }),
+            }],
+        };
+    } catch (err) {
+        return {
+            content: [{
+                type: "text",
+                text: `Error fetching messages: ${err.message}`,
+            }],
+        };
+    }
+}
+
+async function getSurroundingMessages(request) {
+    const { conn, error } = requireActiveConnection();
+    if (error) return error;
+
+    const args = request.params.arguments || {};
+    let messageTimestamp = args.messageTimestamp;
+
+    // Resolve timestamp from messageId if provided
+    if (args.messageId) {
+        const msg = await fetchMessageById(conn.baseUrl, conn.apiToken, args.messageId);
+        if (!msg) {
+            return {
+                content: [{
+                    type: "text",
+                    text: `Message not found: ${args.messageId}`,
+                }],
+            };
+        }
+        messageTimestamp = msg.timestamp;
+    }
+
+    if (!messageTimestamp) {
+        throw new Error("Either messageId or messageTimestamp is required");
+    }
+
+    const targetTime = new Date(messageTimestamp);
+    if (isNaN(targetTime.getTime())) {
+        throw new Error(`Invalid timestamp: ${messageTimestamp}`);
+    }
+
+    const surroundingSeconds = args.surroundingSeconds ?? 5;
+    const from = new Date(targetTime.getTime() - surroundingSeconds * 1000).toISOString();
+    const to = new Date(targetTime.getTime() + surroundingSeconds * 1000).toISOString();
+    const queryString = buildQueryString(args.query, args.filters, args.exactMatch ?? true);
+    const fieldList = resolveFields(args.fields, DEFAULT_FIELDS);
+
+    const payload = {
+        queries: [{
+            id: "q1",
+            query: { type: "elasticsearch", query_string: queryString },
+            timerange: { type: "absolute", from, to },
+            search_types: [{
+                id: "st1",
+                type: "messages",
+                limit: args.limit ?? 50,
+                sort: [{ field: "timestamp", order: "ASC" }],
+            }]
+        }]
+    };
+
+    try {
+        const data = await searchGraylog(conn.baseUrl, conn.apiToken, payload);
+        const { totalResults, extracted } = extractMessages(data, fieldList);
+
+        return {
+            content: [{
+                type: "text",
+                text: JSON.stringify({
+                    target_timestamp: messageTimestamp,
+                    window: { from, to },
+                    total_results: totalResults,
+                    messages: extracted,
+                }),
+            }],
+        };
+    } catch (err) {
+        return {
+            content: [{
+                type: "text",
+                text: `Error fetching surrounding messages: ${err.message}`,
+            }],
+        };
+    }
+}
+
+async function listStreams() {
+    const { conn, error } = requireActiveConnection();
+    if (error) return error;
+
+    try {
+        const data = await fetchStreams(conn.baseUrl, conn.apiToken);
+        const streams = (data.streams || []).map(s => ({
+            id: s.id,
+            title: s.title,
+            description: s.description || "",
+        }));
+
+        return {
+            content: [{
+                type: "text",
+                text: JSON.stringify({ total: data.total || streams.length, streams }),
+            }],
+        };
+    } catch (err) {
+        return {
+            content: [{
+                type: "text",
+                text: `Error fetching streams: ${err.message}`,
+            }],
+        };
+    }
+}
+
+async function listFieldValues(request) {
+    const { conn, error } = requireActiveConnection();
+    if (error) return error;
+
+    const args = request.params.arguments || {};
+    const field = args.field;
+    if (!field) {
+        throw new Error("field is required");
+    }
+
+    const limit = args.limit ?? 20;
+    const queryString = buildQueryString(args.query, args.filters, args.exactMatch ?? true);
+
+    const payload = {
+        queries: [{
+            id: "q1",
+            query: { type: "elasticsearch", query_string: queryString },
+            timerange: { type: "relative", range: args.timeRangeInSeconds ?? 3600 },
+            search_types: [{
+                id: "st1",
+                type: "pivot",
+                row_groups: [{ type: "values", field, limit }],
+                series: [{ type: "count", id: "count" }],
+                rollup: false,
+            }]
+        }]
+    };
+
+    try {
+        const data = await searchGraylog(conn.baseUrl, conn.apiToken, payload);
+        const rows = data?.results?.q1?.search_types?.st1?.rows || [];
+        const values = rows.map(r => ({
+            value: r.key?.[0],
+            count: r.values?.[0]?.value ?? 0,
+        }));
+
+        return {
+            content: [{
+                type: "text",
+                text: JSON.stringify({ field, total: values.length, values }),
+            }],
+        };
+    } catch (err) {
+        return {
+            content: [{
+                type: "text",
+                text: `Error fetching field values: ${err.message}`,
+            }],
+        };
+    }
+}
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/query.js

@@ -0,0 +1,96 @@
+import axios from "axios";
+
+export function buildQueryString(query, filters, exactMatch = true) {
+    let qs;
+    if (!query || query === "*") {
+        qs = "*";
+    } else if (exactMatch && !query.startsWith('"') && !/[*?:()]/.test(query)) {
+        qs = `"${query}"`;
+    } else {
+        qs = query;
+    }
+    if (filters && typeof filters === "object") {
+        for (const [field, value] of Object.entries(filters)) {
+            if (value === undefined || value === null) continue;
+            if (typeof value === "number") {
+                qs += ` AND ${field}:${value}`;
+            } else {
+                qs += ` AND ${field}:"${value}"`;
+            }
+        }
+    }
+    return qs;
+}
+
+export function resolveFields(fieldsParam, defaultFields) {
+    if (fieldsParam === "*") return null; // null = return all fields
+    if (fieldsParam) return fieldsParam.split(",").map(s => s.trim());
+    return defaultFields;
+}
+
+export function extractMessages(responseData, fieldList) {
+    const results = responseData?.results?.q1?.search_types?.st1;
+    const messages = results?.messages || [];
+    const totalResults = results?.total_results || 0;
+
+    const extracted = messages.map(m => {
+        const msg = m.message || {};
+        if (!fieldList) return msg; // null = all fields
+        const picked = {};
+        for (const f of fieldList) {
+            if (msg[f] !== undefined) picked[f] = msg[f];
+        }
+        return picked;
+    });
+
+    return { totalResults, extracted };
+}
+
+export async function fetchMessageById(baseUrl, apiToken, messageId) {
+    const payload = {
+        queries: [{
+            id: "q1",
+            query: { type: "elasticsearch", query_string: `gl2_message_id:${messageId}` },
+            timerange: { type: "relative", range: 86400 },
+            search_types: [{
+                id: "st1",
+                type: "messages",
+                limit: 1,
+            }]
+        }]
+    };
+
+    const data = await searchGraylog(baseUrl, apiToken, payload);
+    const messages = data?.results?.q1?.search_types?.st1?.messages || [];
+    if (messages.length === 0) return null;
+    return messages[0].message;
+}
+
+export async function fetchStreams(baseUrl, apiToken) {
+    const response = await axios.get(`${baseUrl}/api/streams`, {
+        headers: {
+            'Accept': 'application/json',
+            'X-Requested-By': 'graylog-mcp',
+        },
+        auth: {
+            username: apiToken,
+            password: 'token',
+        },
+    });
+    return response.data;
+}
+
+export async function searchGraylog(baseUrl, apiToken, payload) {
+    const response = await axios.post(`${baseUrl}/api/views/search/sync`, payload, {
+        headers: {
+            'Accept': 'application/json',
+            'Content-Type': 'application/json',
+            'X-Requested-By': 'graylog-mcp',
+        },
+        auth: {
+            username: apiToken,
+            password: 'token',
+        },
+    });
+    return response.data;
+}

package/src/tools.js

@@ -0,0 +1,144 @@
+export const toolDefinitions = [
+    {
+        name: "list_connections",
+        description: "List all available Graylog connections configured in ~/.graylog-mcp/config.json",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+    {
+        name: "use_connection",
+        description: "Connect to a specific Graylog instance by name. Must be called before fetching messages.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "The connection name as defined in ~/.graylog-mcp/config.json",
+                },
+            },
+            required: ["name"],
+        },
+    },
+    {
+        name: "fetch_graylog_messages",
+        description: "Fetch messages from the active Graylog connection. Use 'use_connection' first to select a connection.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    description: "The query to search for, with the respective fields and values",
+                },
+                searchTimeRangeInSeconds: {
+                    type: "number",
+                    description: "The time range to search for, in seconds",
+                },
+                pageSize: {
+                    type: "number",
+                    description: "Number of messages per page. Default: 50",
+                },
+                page: {
+                    type: "number",
+                    description: "Page number (starts at 1). Default: 1",
+                },
+                fields: {
+                    type: "string",
+                    description: "Comma-separated field names to return, or '*' for all fields. Default: returns key fields only (timestamp, gl2_message_id, source, env, level, message, logger_name, thread_name, PODNAME)",
+                },
+                filters: {
+                    type: "object",
+                    description: "Field filters (e.g. {\"env\": \"marketplace_loki\", \"level\": 7, \"source\": \"prefr-management\"})",
+                },
+                exactMatch: {
+                    type: "boolean",
+                    description: "If true (default), wraps the query in quotes for exact match. Set to false for fuzzy/wildcard search.",
+                },
+            },
+        },
+    },
+    {
+        name: "get_surrounding_messages",
+        description: "Get messages surrounding a specific message. Provide messageId (preferred) or messageTimestamp to identify the target message.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                messageId: {
+                    type: "string",
+                    description: "gl2_message_id of the target message (preferred). The timestamp will be looked up automatically.",
+                },
+                messageTimestamp: {
+                    type: "string",
+                    description: "ISO timestamp of the target message (fallback if messageId is not available)",
+                },
+                surroundingSeconds: {
+                    type: "number",
+                    description: "Time window in seconds (± around the timestamp). Default: 5",
+                },
+                query: {
+                    type: "string",
+                    description: "Additional query filter to narrow context",
+                },
+                filters: {
+                    type: "object",
+                    description: "Field filters (e.g. {\"env\": \"marketplace_loki\", \"level\": 7})",
+                },
+                exactMatch: {
+                    type: "boolean",
+                    description: "If true (default), wraps the query in quotes for exact match. Set to false for fuzzy/wildcard search.",
+                },
+                limit: {
+                    type: "number",
+                    description: "Maximum number of messages to return. Default: 50",
+                },
+                fields: {
+                    type: "string",
+                    description: "Comma-separated field names to return, or '*' for all fields. Default: returns key fields only (timestamp, gl2_message_id, source, env, level, message, logger_name, thread_name, PODNAME)",
+                },
+            },
+        },
+    },
+    {
+        name: "list_streams",
+        description: "List all available Graylog streams in the active connection.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+    {
+        name: "list_field_values",
+        description: "List distinct values of a field with message counts. Useful for discovering available sources, environments, logger names, etc. Results are sorted by count descending.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                field: {
+                    type: "string",
+                    description: "The field to get distinct values for (e.g. 'source', 'env', 'logger_name', 'level')",
+                },
+                query: {
+                    type: "string",
+                    description: "Query to scope the results (e.g. search within specific messages)",
+                },
+                filters: {
+                    type: "object",
+                    description: "Field filters to narrow scope (e.g. {\"env\": \"marketplace_loki\"})",
+                },
+                exactMatch: {
+                    type: "boolean",
+                    description: "If true (default), wraps the query in quotes for exact match. Set to false for fuzzy/wildcard search.",
+                },
+                timeRangeInSeconds: {
+                    type: "number",
+                    description: "Time range in seconds. Default: 3600 (1 hour)",
+                },
+                limit: {
+                    type: "number",
+                    description: "Maximum number of distinct values to return. Default: 20",
+                },
+            },
+            required: ["field"],
+        },
+    },
+];