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 
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生态系统