MCP Server Graylog

🚀 mcp-server-graylog

mcp-server-graylog 是一款用於 Graylog 日誌搜索的 Model Context Protocol (MCP) 服務器。藉助它，你可以依據絕對或相對時間戳搜索日誌，按流進行過濾，還能直接從 Claude Desktop 調試生產問題。

🚀 快速開始

本項目為生產調試而構建，可使用精確時間戳搜索 Graylog 日誌，按應用流過濾，並獲取用於排查生產問題的可行見解。

✨ 主要特性

• ✅ 絕對時間戳搜索：使用精確的時間範圍調試特定錯誤。
• ✅ 相對時間戳搜索：搜索最近的日誌（過去 N 秒）。
• ✅ 流發現：列出所有可用的流/應用程序。
• ✅ 系統健康檢查：驗證 Graylog 連接性。
• ✅ 全面驗證：支持 ISO 8601 時間戳、查詢語法、流 ID。
• ✅ 清晰的錯誤消息：針對身份驗證、網絡和 API 問題提供可操作的錯誤信息。
• ✅ 超時處理：30 秒超時設置，防止請求掛起。
• ✅ 生產就緒：通過 54 項測試，代碼質量評分為 9.2/10。

📦 安裝指南

選項 1：使用 npx（推薦）

# 無需安裝 - 直接使用 npx
npx mcp-server-graylog

選項 2：全局安裝

npm install -g mcp-server-graylog

選項 3：本地安裝

# 克隆倉庫
git clone https://github.com/Pranavj17/mcp-server-graylog.git
cd mcp-server-graylog

# 安裝依賴
npm install

💻 使用示例

可用工具

1. search_logs_absolute

使用絕對時間戳（從/到）搜索日誌。非常適合調試具有特定時間戳的錯誤，這些時間戳可來自監控工具或錯誤跟蹤系統。 參數：

• query（必需）：使用 Elasticsearch 語法的搜索查詢。
• from（必需）：ISO 8601 格式的開始時間戳。
• to（必需）：ISO 8601 格式的結束時間戳。
• streamId（可選）：用於過濾結果的流 ID。
• limit（可選）：最大結果數（默認值：50，最大值：1000）。

示例：

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

使用相對時間範圍（例如，過去 15 分鐘）搜索日誌。適用於最近的日誌分析。 參數：

• query（必需）：使用 Elasticsearch 語法的搜索查詢。
• rangeSeconds（可選）：以秒為單位的時間範圍（默認值：900 = 15 分鐘，最大值：86400 = 24 小時）。
• streamId（可選）：用於過濾結果的流 ID。
• limit（可選）：最大結果數（默認值：50，最大值：1000）。

示例：

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

3. list_streams

列出所有可用的 Graylog 流（應用程序）。用於發現用於過濾的流 ID。 參數：無 返回值：

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

4. get_system_info

獲取 Graylog 系統信息和健康狀態。驗證連接性並檢查服務器版本。 參數：無 返回值：

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

查詢示例

搜索錯誤

level:ERROR

搜索特定端點

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

搜索 HTTP 狀態碼

status:500
status:>=400

搜索用戶操作

user_id:12345 AND action:login

搜索慢請求

duration_ms:>1000

搜索異常

exception:NullPointerException

組合多個條件

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

使用通配符搜索

message:*connection refused*

按字段存在性搜索

_exists_:error_code

常見用例

1. 調試生產錯誤

當從監控系統獲得帶有時間戳的錯誤時：

1. 從監控工具複製錯誤時間戳。
2. 使用 search_logs_absolute 並設置 ±5 分鐘的時間窗口。
3. 按應用程序流過濾。
4. 在日誌中查找根本原因。

2. 監控最近的部署

部署後：

1. 使用 search_logs_relative 搜索過去 15 分鐘的日誌。
2. 搜索 level:ERROR。
3. 驗證是否未引入新錯誤。

3. 調查 API 故障

當 API 端點失敗時：

1. 搜索端點路徑："/api/v1/endpoint"。
2. 按狀態碼過濾：status:>=400。
3. 檢查錯誤模式。

📚 詳細文檔

配置

Claude Desktop 設置

將以下內容添加到你的 Claude Desktop 配置文件中：

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

使用 npx（推薦）

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

使用本地安裝

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

環境變量

變量	是否必需	描述
BASE_URL	是	Graylog 服務器 URL（例如，https://graylog.example.com）
API_TOKEN	是	Graylog API 令牌（基本身份驗證的用戶名，密碼為 "token"）

獲取 Graylog API 令牌

1. 登錄到 Graylog 網頁界面。
2. 轉到 System → Users。
3. 選擇你的用戶。
4. 點擊 Edit tokens。
5. 創建一個具有讀取權限的新令牌。
6. 複製令牌值。

常見錯誤信息

錯誤	含義	解決方案
Authentication failed	API 令牌無效	檢查配置中的 API_TOKEN
Invalid query	Elasticsearch 語法錯誤	檢查查詢語法和參數
Endpoint not found	Graylog URL 錯誤	檢查配置中的 BASE_URL
Cannot reach Graylog	網絡連接問題	驗證 Graylog 是否可訪問
Invalid timestamp	時間戳格式錯誤	使用 ISO 8601 格式（例如，2025-10-23T10:00:00.000Z）

故障排除

服務器無法啟動

檢查環境變量：

# 驗證 BASE_URL 和 API_TOKEN 是否在 Claude Desktop 配置中設置
# 檢查 Claude Desktop 日誌：
# macOS: ~/Library/Logs/Claude/mcp*.log
# Windows: %APPDATA%\Claude\logs\mcp*.log

驗證 Graylog 可訪問性：

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

身份驗證錯誤

• 驗證 API 令牌在 Graylog 中具有讀取權限。
• 令牌格式：使用令牌值作為用戶名，"token" 作為密碼。
• 檢查令牌是否未過期。

未返回結果

• 使用 list_streams 工具驗證流 ID 是否正確。
• 檢查時間戳範圍是否包含數據。
• 嘗試將查詢簡化為 * 以查看是否存在任何數據。
• 驗證流是否未禁用。

集成測試失敗

# 設置集成測試的環境變量
export INTEGRATION_TESTS=true
export BASE_URL=https://graylog.example.com
export API_TOKEN=your_token_here

# 運行集成測試
npm run test:integration

開發

前提條件

• Node.js >= 18.0.0
• npm >= 8.0.0
• 訪問 Graylog 實例（用於集成測試）

開發工作流程

# 安裝依賴
npm install

# 在開發模式下運行（自動重新加載）
npm run dev

# 運行測試
npm test

# 在監視模式下運行測試
npm run test:watch

# 僅運行單元測試
npm run test:unit

# 運行集成測試（需要 Graylog 實例）
INTEGRATION_TESTS=true BASE_URL=https://graylog.example.com API_TOKEN=xxx npm run test:integration

# 檢查語法
npm run lint

項目結構

mcp-server-graylog/
├── src/
│   └── index.js           # 主服務器實現（429 行）
├── test/
│   ├── helpers.test.js    # 輔助函數測試（14 項測試）
│   ├── validation.test.js # 輸入驗證測試（24 項測試）
│   ├── mcp-protocol.test.js # MCP 協議測試（16 項測試）
│   └── integration.test.js  # 集成測試（7 項測試）
├── example-config.json    # Claude Desktop 配置示例
├── CONTRIBUTING.md        # 貢獻指南
├── CHANGELOG.md          # 版本歷史
└── package.json         # npm 配置

運行測試

# 運行所有測試（54 項測試）
npm test

# 預期輸出：
# tests 54
# pass 54
# fail 0

架構

簡單、專注的架構，僅在一個文件中（429 行）：

• 配置與驗證：檢查環境變量。
• 輔助函數：ISO 8601 驗證、錯誤格式化。
• MCP 服務器設置：標準 MCP 協議實現。
• 工具定義：4 個工具，具有清晰的架構。
• 工具實現：乾淨、經過驗證的函數。
• 服務器啟動：驗證後連接。

設計原則：

• ✓ 簡單且易於維護
• ✓ 單文件，易於理解
• ✓ 關注點清晰分離
• ✓ 全面的錯誤處理
• ✓ 邊界處的輸入驗證
• ✓ 一致的響應格式

貢獻

歡迎貢獻！請參閱 CONTRIBUTING.md 獲取指南。 快速開始：

1. 分叉倉庫。
2. 創建功能分支。
3. 為你的更改添加測試。
4. 確保所有測試通過（npm test）。
5. 提交拉取請求。

變更日誌

請參閱 CHANGELOG.md 瞭解版本歷史和發佈說明。

安全

• 使用環境變量存儲敏感數據（絕不硬編碼）。
• 正確實現基本身份驗證。
• 輸入驗證可防止注入攻擊。
• 超時設置可防止掛起請求。
• 錯誤消息不會洩露敏感信息。

若要報告安全漏洞，請在 GitHub 上創建私人安全建議。

🔧 技術細節

本項目採用簡單且專注的架構，核心代碼集中在一個文件（src/index.js，共 429 行）中實現。主要包含以下幾個部分：

• 配置與驗證：對環境變量進行檢查，確保服務器啟動時所需的配置信息正確無誤。
• 輔助函數：提供 ISO 8601 時間戳驗證、錯誤格式化等功能，增強代碼的複用性和可維護性。
• MCP 服務器設置：按照標準的 MCP 協議進行服務器的初始化和配置，確保與其他系統的兼容性。
• 工具定義：明確了 4 個工具（search_logs_absolute、search_logs_relative、list_streams、get_system_info）的輸入輸出模式，使得各個工具的功能和使用方式清晰明瞭。
• 工具實現：針對每個工具編寫了具體的實現函數，這些函數經過嚴格的驗證和測試，保證了功能的正確性和穩定性。
• 服務器啟動：在啟動服務器之前，會對配置信息進行驗證，驗證通過後才會建立與 Graylog 的連接。

這種架構設計遵循了簡單和可維護的原則，將各個功能模塊清晰地分離，便於開發者理解和擴展。同時，全面的錯誤處理機制和輸入驗證機制，提高了系統的健壯性和安全性。

📄 許可證

本項目採用 MIT 許可證 - 詳情請參閱 LICENSE 文件。

🔗 鏈接

• npm 包
• GitHub 倉庫
• 問題跟蹤器
• Model Context Protocol
• Graylog 文檔

🙏 致謝

• 使用 @modelcontextprotocol/sdk 構建。
• 受 MCP 社區的啟發。
• 感謝所有貢獻者！

---

為 Claude Desktop 社區用心打造 ❤️

如有問題或需要支持，請在 GitHub 上創建問題