log-mcp-python

Remote log query service based on MCP (Model Context Protocol), implemented in Python.

This project is a redesign and reimplementation of the open-source Log-MCP (Java version): it exposes exactly the same MCP tool interface externally (JSON-RPC 2.0, STDIO / HTTP transport modes), while internally restructuring the overall architecture following Python conventions, and abstracting the "log retrieval method" into a pluggable execution channel — the specific commands for retrieving logs are always built by the service, and only the channels that execute the commands vary.

Features

• Interface compatible: 5 MCP tools identical to the original Java version (search_logs / tail_logs / read_log_file / list_log_files / list_servers), with aligned input/output contracts.

• Pluggable execution channels:

  • ssh — SSH private key direct connection (paramiko, with connection pool and auto-reconnect)

  • pyinfra — reuse existing pyinfra host assets (supports host specs such as @local, root@host:22)

  • local — local execution (development / testing)

• Unified command building: all log operations are normalized into a shell command executed on the target machine (grep -n -A -B / tail -n / sed -n / find), decoupled from the execution channel — adding a new channel only requires implementing CommandExecutor.execute().

• Security: parameter validation, relative path validation, dangerous character detection, and shell single-quote escaping consistent with the original version.

• Zero heavy dependencies: core depends only on paramiko; pyinfra is an optional dependency, installed only when the pyinfra channel is used.

Related MCP server: jakubs-mcp-tools

Architecture

MCP 客户端（AI 助手 / IDE）
        │  JSON-RPC 2.0
        ▼
mcp/            传输与协议层（stdio_server / http_server / handler）
        ▼
tools.py        5 个工具的声明式定义（名称 + JSON Schema + 处理函数）
        ▼
service/        业务编排层（参数校验 → 文件推导 → 命令构建 → 解析）
        ▼
executors/      可插拔执行通道（ssh_key / pyinfra_exec / local + registry）
        ▼
目标服务器上的 shell 命令（grep / tail / sed / find）

Detailed design is in docs/DESIGN.md.

Installation

pip install .            # 核心功能（ssh + local 通道）
pip install .[pyinfra]   # 需要 pyinfra 通道时
pip install .[dev]       # 运行测试

Configuration

Refer to config.example.json. It is compatible with the original Java version's config.json structure, with the following extensions:

• Each server independently specifies its execution channel via the connector field: ssh (default) / pyinfra / local

• The pyinfra channel supports pyinfraHost (full host spec, e.g. root@192.168.5.20:22 or @local) and pyinfraData (host data passed through to pyinfra, e.g. ssh_key)

• Strings support ${VAR} environment variable placeholders (left as-is if undefined)

{
  "servers": [
    {
      "name": "ssh-server",
      "connector": "ssh",
      "host": "192.168.5.169",
      "port": 22,
      "username": "root",
      "privateKeyPath": "${SSH_KEY_PATH}",
      "logRootPath": "/home/docker/logs/myapp/",
      "default": true
    },
    {
      "name": "pyinfra-server",
      "connector": "pyinfra",
      "pyinfraHost": "root@192.168.5.20:22",
      "pyinfraData": { "ssh_key": "/root/.ssh/id_rsa" },
      "logRootPath": "/var/logs/app/"
    },
    {
      "name": "dev-local",
      "connector": "local",
      "logRootPath": "/tmp/logs/"
    }
  ],
  "logLevels": ["info", "warn", "error", "debug"],
  "logFilePattern": "{level}/log-{level}-{date}.{seq}.log"
}

Key field descriptions:

Running

# STDIO 模式（MCP 客户端拉起，默认）
log-mcp --config config.json

# HTTP 模式（独立部署，端口默认 8892，路径 / 与 /mcp，健康检查 GET /health）
log-mcp --config config.json --transport http --port 8892

Environment variables are also supported: LOG_CONFIG, TRANSPORT_MODE, SERVER_PORT.

Connecting to an MCP client (HTTP mode as an example):

{
  "mcpServers": {
    "log-mcp": {
      "url": "http://your-host:8892/mcp"
    }
  }
}

STDIO mode connection:

{
  "mcpServers": {
    "log-mcp": {
      "command": "log-mcp",
      "args": ["--config", "/path/to/config.json"]
    }
  }
}

MCP Tools

Call example (HTTP):

curl -s -X POST http://127.0.0.1:8892/mcp -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"search_logs","arguments":{"keyword":"ERROR","levels":["error","info"]}}}'

Testing

python -m pytest tests/ -q

Test coverage: parameter/path validation, shell escaping, command building, grep output parsing (including deterministic parsing of known files), JSON-RPC protocol handling, and end-to-end integration tests for the local / pyinfra(@local) channels (100 test cases in total).

License

Apache-2.0