{
  "markdown": "<!-- mcp-name: io.github.kascada/logmcp -->\n# LogMCP\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![logmcp MCP server](https://glama.ai/mcp/servers/kascada/logmcp/badges/score.svg)](https://glama.ai/mcp/servers/kascada/logmcp)\n\nMCP server — read-only log access for AI assistants. Debug your Linux server with AI, without giving the AI shell access.\n\nNo SSH. No write permissions. The AI reads your logs over HTTPS and helps you diagnose problems, while your server stays fully under your control.\n\nLogMCP is an open-source [MCP](https://modelcontextprotocol.io) server that exposes log files on a remote Linux server to AI assistants (Claude Code, VS Code, Claude Desktop). Access is read-only, token-authenticated, and fully audited via syslog.\n\n## Get Started\n\n### Option A: Quickstart (no root required)\n\nTry LogMCP in under a minute — no config file, no root, no systemd:\n\n```sh\nlogmcp quickstart\n```\n\nThe command checks your group memberships (`adm`, `systemd-journal`), generates a bearer token and a self-signed TLS certificate, starts the server, and prints a ready-to-paste `claude mcp add` command.\n\n**Running as root?** Pass `--user <name>` and LogMCP will add the user to the required groups and re-launch as that user — root is not needed for future starts.\n\n> **Note:** Token and certificate are ephemeral. The token changes on every start. For a permanent setup use Option B.\n\n```sh\nlogmcp quickstart --port 7789 --token mytoken   # optional flags\n```\n\nAfter testing, remove the server from Claude Code:\n\n```sh\nclaude mcp remove logmcp-quickstart\n```\n\n---\n\n### Option B: Permanent installation (recommended)\n\n**1. Install**\n\n```sh\ngo install github.com/kascada/logmcp@latest\n```\n\nOr install the pre-built `.deb` (replace `x.y.z` with the [latest version](https://github.com/kascada/logmcp/releases)):\n\n```sh\ncurl -LO https://github.com/kascada/logmcp/releases/download/vx.y.z/logmcp_x.y.z_amd64.deb\nsudo dpkg -i logmcp_x.y.z_amd64.deb\n```\n\n**2. Run the setup wizard**\n\n```sh\nsudo logmcp setup\n```\n\nGuides you through TLS mode, bearer token, and systemd service — then prints a ready-to-paste client config snippet.\n\n**3. Add to your AI client**\n\n```sh\nlogmcp client-config claude-code   # or: vscode | claude-desktop\n```\n\nPaste the output into your MCP client config. Done — your AI can now read the server's logs.\n\n---\n\n## The Key Advantage: Let the AI Debug Without Touching Your Server\n\nYou give the AI a read-only window into your logs. That's it.\n\n- No SSH access required — the AI connects like any HTTPS client\n- No write permissions — the AI cannot change, delete, or execute anything\n- No shell access — not even read access beyond the whitelisted log paths\n- Works from anywhere — your laptop, Claude Desktop, a remote CI agent\n- Every access is audited via syslog on the server\n\nThis makes LogMCP ideal for situations where you need AI-assisted debugging but cannot or do not want to grant shell access: production servers, customer machines, hardened environments, or any setup where least-privilege matters.\n\n> **SSH is also supported.** If your AI client is Claude Code running locally with an SSH key, you can use LogMCP over an SSH tunnel instead of a public HTTPS endpoint. See [SSH Tunnel Setup](#ssh-tunnel-setup) below.\n\n## Features\n\n- Read-only access to log files — the AI cannot modify anything\n- Whitelist/blacklist glob patterns for fine-grained access control\n- systemd journal (`journald://`) as a virtual log source\n- Multi-token auth — per-client bearer tokens with revocation\n- External authenticator support — delegate token verification to any CLI program\n- TLS support: self-signed, custom cert, or behind Caddy reverse proxy\n- Audit trail via syslog (access only, no log content)\n- Guided interactive setup wizard\n- Systemd service integration\n- Extensions — expose external CLI tools or Redis-RPC workers as additional MCP tools\n- Macros — define composite MCP tools as YAML files, no code required\n- fail2ban integration and in-process rate limiting\n\n## Setup Details\n\nThe wizard (`sudo logmcp setup`) covers:\n- Deployment mode (direct TLS or behind Caddy)\n- Port and bearer token configuration\n- Systemd service installation\n- Client configuration snippets for Claude Code, VS Code, and Claude Desktop\n\nWhitelist/blacklist and journald are configured directly in `/etc/logmcp/config.yaml` after setup.\n\n## Environment variable substitution\n\nAny value in `config.yaml` can reference environment variables using `${VAR}` or `$VAR` syntax. The substitution happens before the file is parsed, so it works everywhere — tokens, paths, DSNs, etc.\n\n```yaml\nauth:\n  tokens:\n    - name: claude\n      token: ${LOGMCP_TOKEN}\n      scopes: [read]\n\nextensions:\n  clitool:\n    - name: switchboard\n      command: /usr/local/bin/switchboard\n      timeout_seconds: 10\n```\n\nUnset variables expand to an empty string. To keep a literal `$` in a value, use `$$`.\n\nAfter setup, start the server:\n\n```sh\nsudo systemctl start logmcp\n```\n\n## Commands\n\n| Command | Description |\n|---|---|\n| `logmcp serve` | Start the MCP server (default) |\n| `logmcp quickstart` | Start instantly without config file (no root required) |\n| `logmcp setup` | Interactive setup wizard |\n| `logmcp check` | Verify configuration and environment |\n| `logmcp token list` | List configured bearer tokens |\n| `logmcp token add --name <n>` | Add a new bearer token |\n| `logmcp token remove <name>` | Remove a bearer token |\n| `logmcp token renew <name>` | Generate a new value for an existing token |\n| `logmcp logs list` | List accessible log files |\n| `logmcp logs read <path>` | Read a log file or `journald://` |\n| `logmcp logs search <path>` | Search a log file or `journald://` |\n| `logmcp logs info <path>` | Show log file metadata |\n| `logmcp service install` | Install systemd service |\n| `logmcp service remove` | Remove systemd service |\n| `logmcp service status` | Show service status |\n| `logmcp service caddy-snippet` | Print Caddyfile configuration |\n| `logmcp client-config claude-code` | Print Claude Code MCP config |\n| `logmcp client-config vscode` | Print VS Code MCP config |\n| `logmcp client-config claude-desktop` | Print Claude Desktop MCP config |\n| `logmcp security install-fail2ban` | Install fail2ban filter and jail for logmcp |\n\n## MCP Tools\n\nThese are the tools LogMCP exposes to AI assistants:\n\n| Tool | Description |\n|---|---|\n| `list_logs` | List all log files the server has been configured to expose |\n| `read_log` | Read lines from a log file — head, tail, offset, or time window |\n| `search_log` | Search a log file by regexp with optional context lines and time filter |\n| `log_info` | File metadata: size, line count, last modified |\n| `check_environment` | Server-side health checks (config, TLS, whitelist, syslog, databases) |\n| `check_config` | Show current server configuration and optional parameters at their defaults |\n| `server_status` | Runtime status of the MCP layer and registered extensions |\n\nExtensions may add further tools — their names are prefixed with the extension name (e.g. `myapp_status` for an extension named `myapp`).\n\n## Extensions — Wrapping External Tools as MCP\n\nLogMCP can expose any external program or service as additional MCP tools — no custom MCP server required. The AI sees them alongside the built-in log tools.\n\n### CLI extension\n\nAny program that implements the [`clitool` interface](docs/CLITOOL.md) (`list` / `call` subcommands) can be registered. LogMCP calls `<command> list` at startup to discover tools, and forwards each tool call to `<command> call <tool> --token-stdin`.\n\n```yaml\nextensions:\n  clitool:\n    - name: myapp\n      command: /usr/local/bin/myapp-ctl\n      timeout_seconds: 10\n```\n\nThis spawns a subprocess per call — suitable for any program on the same or a remote host.\n\n### RPC extension (Redis)\n\nFor programs running on the same host, the RPC variant avoids the per-call process-startup overhead (relevant for Python programs where interpreter startup and imports add noticeable latency). Instead of spawning a subprocess, LogMCP pushes a request onto a Redis list and waits for the worker's reply.\n\n```yaml\nextensions:\n  clitool:\n    - name: myapp\n      command: /usr/local/bin/myapp-ctl   # still used for `list` at startup\n      mode: rpc\n      redis_addr: \"127.0.0.1:6379\"\n      timeout_seconds: 5\n```\n\nThe worker reads requests from a Redis list and pushes its reply to a per-request reply key. See [docs/RPC.md](docs/RPC.md) for the full protocol.\n\n### Auth flow\n\nThe bearer token from each incoming MCP request is forwarded to the extension — either via stdin (CLI mode) or as `caller` metadata in the RPC envelope. The extension can verify it or trust the pre-resolved identity.\n\n---\n\n## Case Studies\n\nReal-world scenarios where LogMCP makes the difference — see [docs/case-studies.md](docs/case-studies.md):\n\n- [Asterisk/VoIP — Paket-Kompilierung und Abhängigkeitsfehler debuggen](docs/case-studies.md#asterisk--voip-server--paket-kompilierung-und-abh%C3%A4ngigkeitsfehler-debuggen)\n- [Webserver mit Caddy Reverse Proxy — produktive Installation](docs/case-studies.md#webserver-mit-caddy-reverse-proxy--produktive-installation)\n- [Standalone-Betrieb mit eigenem TLS](docs/case-studies.md#standalone-betrieb-mit-eigenem-tls)\n\n## SSH Tunnel Setup\n\nIf you are using Claude Code locally and already have SSH access to the server, you can run LogMCP without a public HTTPS endpoint:\n\n```sh\n# Forward remote port 7788 to localhost\nssh -L 7788:127.0.0.1:7788 user@yourserver\n\n# Then point your MCP client at https://localhost:7788\n```\n\nLogMCP still requires a bearer token over the tunnel — the SSH layer adds transport security, the token controls which client can connect.\n\n## License\n\nMIT License — see [LICENSE](LICENSE).\n",
  "bytes": 9773,
  "sha": "791f475cccb262f69dddac6607d32efea90928622446f823d8b4e33fe2ac860b",
  "repo_slug": "kascada/logmcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_kascada_logmcp_2ef7cd23/readme"
}