AI导哈

日志查询服务

一个提供只读访问systemd journalctl的MCP服务器，适用于AI助手调试系统问题、分析日志和监控Linux系统服务。

  • by kcalvelli
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 kcalvelli/mcp-journal

使用说明

MCP日志服务器

一种模型上下文协议（MCP）服务器，提供对systemd-journalctl的只读访问。

仅限Linux -需要systemd和journalctl。

概述

此MCP服务器提供了三个用于查询systemd日志和单元状态的工具：

  • logs.query -具有过滤功能的灵活日记查询
  • logs.tail -最近日志（最近1分钟）
  • 单位.状态 -系统单元状态（共有保护）

非常适合AI助手帮助调试系统问题、分析日志和监控Linux系统上的服务。

快速开始

# Run the server
python3 src/mcp_journal.py

# Run tests
python3 TESTS/acceptance_harness.py

需求

  • 带systemd的Linux系统 （Ubuntu、Fedora、Arch、NixOS等）
  • Python 3.8+
  • 用户在 systemd-journal 群组

注： 此工具需要systemd和journalctl，它们仅适用于Linux。

与MCP客户端一起使用

Cline（VSCode扩展）

这是Linux的推荐MCP客户端。

  1. 安装 临床扩展 在VSCode中
  2. 打开Cline设置并添加MCP服务器：
{
  "mcpServers": {
    "journal": {
      "command": "python3",
      "args": ["/absolute/path/to/mcp-journal/src/mcp_journal.py"]
    }
  }
}

对于NixOS用户：

{
  "mcpServers": {
    "journal": {
      "command": "nix",
      "args": ["run", "github:kcalvelli/mcp-journal"]
    }
  }
}

MCP检验员（测试）

# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Test the server
mcp-inspector python3 src/mcp_journal.py

使用服务器

配置后，询问：

  • “显示最近20个nginx错误日志”
  • “我的SSH服务的状态如何？”
  • “查找与'timeout'匹配的最近一小时的所有日志”

查询示例

# Get last 10 journal entries
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"logs.query","arguments":{"limit":10}}}' | \
    python3 src/mcp_journal.py 2>/dev/null | jq .

# Tail nginx logs
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"logs.tail","arguments":{"unit":"nginx.service"}}}' | \
    python3 src/mcp_journal.py 2>/dev/null | jq .

# Check systemd-journald status
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"units.status","arguments":{"unit":"systemd-journald.service"}}}' | \
    python3 src/mcp_journal.py 2>/dev/null | jq .

建筑

MCP Client (Claude) → stdio → mcp_journal.py → journalctl/systemctl

看 IMPLEMENTATION.md 详细的架构。

安全

  • ✅ 只读（无系统修改）
  • ✅ 以调用用户身份运行（无权限提升）
  • ✅ units.status的允许列表（防止枚举）
  • ✅ 资源限制（最多2000个条目，超时30秒）
  • ✅ 无shell注入（使用子进程argv数组）

看 SPECS/08-security.md 对于完整的威胁模型。

测试

# Full acceptance suite (9 tests)
python3 TESTS/acceptance_harness.py

# Quick smoke tests
bash TESTS/smoke-test.sh

所有测试均已通过✅

文档

  • 实施.md -实施细节和使用方法
  • 计划.md -全面实施计划（8个阶段，73项任务）
  • TASKS.md -详细的任务跟踪
  • 规格/ -完整的规范（9份文件，1872行）
    • 01-constitution.md-核心约束
    • 02-architecture.md-系统设计
    • 03-cli.md-命令行界面
    • 04-tools.md-工具规格
    • 05-interface.mcp.json-mcp接口（规范）
    • 06-data-schemas.json-字段映射
    • 07-testing.md-测试策略
    • 08-security.md-安全模型
    • 09-nix.md-尼克斯包装

项目状态

✅ 已完成（MVP）

  • [x] Python MCP服务器实现（543行）
  • [x] 全部3个工具：logs.query、logs.tail、units.status
  • [x] 根据规范进行现场测绘
  • [x] 允许名单执行
  • [x] 验收测试线束（9项测试）
  • [x] 烟雾测试
  • [x] 完整的规格（9份文件）
  • [x] 实施计划（8个阶段）

🚧 进行中

  • [ ] --allow-units CLI标志
  • []镍包装（flake.Nix）
  • []带有模拟的单元测试

📋 计划的

  • []速率限制（v1.1）
  • []字段级编辑（v1.1）
  • []CI/CD工作流程
  • []PyPI发布（可选）

看 TASKS.md 完成任务分解（8个阶段73个任务）。

贡献

看 CONTRIBUTING.md （待创建）用于开发设置。

开始：

git clone <repo>
cd mcp-journal
python3 TESTS/acceptance_harness.py  # Run tests

许可证

MIT许可证-请参阅 许可证 详细信息文件

链接

  • MCP协议：https://modelcontextprotocol.io
  • 临床VSCode扩展：https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev
  • 系统d：https://systemd.io
  • journalctl：https://man.archlinux.org/man/journalctl.1

内置❤️ 对于MCP生态系统

相关 MCP