LogMCP is a read-only MCP server that gives AI assistants secure, audited access to log files on a remote Linux server without requiring SSH or shell access. Access is token-authenticated over HTTPS, limited to whitelisted paths, and every access is audited via syslog.
Core Log Access
list_logs — Discover all configured log files, including size, last modified time, line count, and readability status
read_log — Read lines from a log file with head/tail, offset pagination, and time-based filtering (RFC3339 timestamps or relative durations like 1h, 30m)
search_log — Search using Go regular expressions, with optional context lines and time window filtering (up to 200 matches by default)
log_info — Retrieve metadata (size, line count, last modified) for a specific log file
Server Diagnostics
check_environment — Health checks covering configuration validity, TLS setup, log whitelist, syslog, and database connectivity
check_config — View current server settings and optional parameters still at their defaults
server_status — Check if the MCP layer is responding, how many tools are registered, and whether extensions are accessible
Extensions & Security
Expose external CLI tools or Redis RPC workers as additional MCP tools
Multi-token authentication with revocation, whitelist/blacklist control, and fail2ban integration
Supports direct TLS, Caddy reverse proxy, or SSH tunnels for deployment
MCP server — read-only log access for AI assistants. Debug your Linux server with AI, without giving the AI shell access.
No SSH. No write permissions. The AI reads your logs over HTTPS and helps you diagnose problems, while your server stays fully under your control.
LogMCP is an open-source MCP 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.
Try LogMCP in under a minute — no config file, no root, no systemd:
logmcp quickstartThe 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.
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.
Note: Token and certificate are ephemeral. The token changes on every start. For a permanent setup use Option B.
logmcp quickstart --port 7789 --token mytoken # optional flagsAfter testing, remove the server from Claude Code:
claude mcp remove logmcp-quickstart1. Install
go install github.com/kascada/logmcp@latestOr install the pre-built .deb (replace x.y.z with the latest version):
curl -LO https://github.com/kascada/logmcp/releases/download/vx.y.z/logmcp_x.y.z_amd64.deb
sudo dpkg -i logmcp_x.y.z_amd64.deb2. Run the setup wizard
sudo logmcp setupGuides you through TLS mode, bearer token, and systemd service — then prints a ready-to-paste client config snippet.
3. Add to your AI client
logmcp client-config claude-code # or: vscode | claude-desktopPaste the output into your MCP client config. Done — your AI can now read the server's logs.
Related MCP server: log-mcp
You give the AI a read-only window into your logs. That's it.
No SSH access required — the AI connects like any HTTPS client
No write permissions — the AI cannot change, delete, or execute anything
No shell access — not even read access beyond the whitelisted log paths
Works from anywhere — your laptop, Claude Desktop, a remote CI agent
Every access is audited via syslog on the server
This 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.
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 below.
Read-only access to log files — the AI cannot modify anything
Whitelist/blacklist glob patterns for fine-grained access control
systemd journal (journald://) as a virtual log source
Multi-token auth — per-client bearer tokens with revocation
External authenticator support — delegate token verification to any CLI program
TLS support: self-signed, custom cert, or behind Caddy reverse proxy
Audit trail via syslog (access only, no log content)
Guided interactive setup wizard
Systemd service integration
Extensions — expose external CLI tools or Redis-RPC workers as additional MCP tools
Macros — define composite MCP tools as YAML files, no code required
fail2ban integration and in-process rate limiting
The wizard (sudo logmcp setup) covers:
Deployment mode (direct TLS or behind Caddy)
Port and bearer token configuration
Systemd service installation
Client configuration snippets for Claude Code, VS Code, and Claude Desktop
Whitelist/blacklist and journald are configured directly in /etc/logmcp/config.yaml after setup.
Any 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.
auth:
tokens:
- name: claude
token: ${LOGMCP_TOKEN}
scopes: [read]
extensions:
clitool:
- name: switchboard
command: /usr/local/bin/switchboard
timeout_seconds: 10Unset variables expand to an empty string. To keep a literal $ in a value, use $$.
After setup, start the server:
sudo systemctl start logmcpCommand | Description |
| Start the MCP server (default) |
| Start instantly without config file (no root required) |
| Interactive setup wizard |
| Verify configuration and environment |
| List configured bearer tokens |
| Add a new bearer token |
| Remove a bearer token |
| Generate a new value for an existing token |
| List accessible log files |
| Read a log file or |
| Search a log file or |
| Show log file metadata |
| Install systemd service |
| Remove systemd service |
| Show service status |
| Print Caddyfile configuration |
| Print Claude Code MCP config |
| Print VS Code MCP config |
| Print Claude Desktop MCP config |
| Install fail2ban filter and jail for logmcp |
These are the tools LogMCP exposes to AI assistants:
Tool | Description |
| List all log files the server has been configured to expose |
| Read lines from a log file — head, tail, offset, or time window |
| Search a log file by regexp with optional context lines and time filter |
| File metadata: size, line count, last modified |
| Server-side health checks (config, TLS, whitelist, syslog, databases) |
| Show current server configuration and optional parameters at their defaults |
| Runtime status of the MCP layer and registered extensions |
Extensions may add further tools — their names are prefixed with the extension name (e.g. myapp_status for an extension named myapp).
LogMCP 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.
Any program that implements the clitool interface (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.
extensions:
clitool:
- name: myapp
command: /usr/local/bin/myapp-ctl
timeout_seconds: 10This spawns a subprocess per call — suitable for any program on the same or a remote host.
For 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.
extensions:
clitool:
- name: myapp
command: /usr/local/bin/myapp-ctl # still used for `list` at startup
mode: rpc
redis_addr: "127.0.0.1:6379"
timeout_seconds: 5The worker reads requests from a Redis list and pushes its reply to a per-request reply key. See docs/RPC.md for the full protocol.
The 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.
Real-world scenarios where LogMCP makes the difference — see docs/case-studies.md:
If you are using Claude Code locally and already have SSH access to the server, you can run LogMCP without a public HTTPS endpoint:
# Forward remote port 7788 to localhost
ssh -L 7788:127.0.0.1:7788 user@yourserver
# Then point your MCP client at https://localhost:7788LogMCP still requires a bearer token over the tunnel — the SSH layer adds transport security, the token controls which client can connect.
MIT License — see LICENSE.
Show the current LogMCP server configuration and highlight optional parameters that are at their default value.
Use to understand how this server is configured — which logs are accessible, whether proxy mode or fail2ban are active, which tools are enabled, and which optional features are not yet configured. See logmcp://docs/config for the full configuration reference.
Object with two fields:
current — key configuration values currently active on this server
defaults — optional parameters that are at their default value, each with a short explanation of what they do
Inputs: no named parameters.
Run a set of server-side environment checks and return their pass/fail status. Covers configuration validity, TLS setup, log file whitelist, syslog connectivity, and database connectivity.
Use to verify that the LogMCP server is configured correctly and that all configured backends are reachable. Useful when diagnosing why a tool is not working as expected, or after a configuration change.
Array of check result objects, each with:
name — check identifier (e.g. config, tls, whitelist, syslog)
ok — true if the check passed, false if it failed
detail — human-readable description of the result or error (omitted when empty)
Inputs: no named parameters.
List all log files the server has been configured to expose. Returns an array of file entries ordered by path.
Call this first to discover which log files are available before calling read_log, search_log, or log_info. If you do not know the exact path of a log file, always call list_logs first.
Array of objects, each with:
path — absolute path on the server
size_bytes — file size in bytes
last_modified — last-modified timestamp (RFC3339)
line_count — total number of lines
readable — whether the file is accessible by the server process
Inputs: no named parameters.
Return metadata for a single log file: size, line count, and last-modified timestamp.
Use to check whether a log file has changed recently, or to determine its total size and line count before deciding how many lines to read with read_log.
Absolute path to the log file. Obtain valid paths from list_logs.
path — file path
size_bytes — file size in bytes
line_count — total number of lines in the file
last_modified — last-modified timestamp (RFC3339)
readable — whether the file is accessible by the server process
Inputs: path (required).
Read lines from a log file. Supports reading from the beginning or end, with optional time-based filtering.
Use to inspect a specific portion of a log file. Use tail: true for the most recent entries. Use since/until to narrow to a specific time window. For targeted pattern matching, prefer search_log instead.
Absolute path to the log file. Obtain valid paths from list_logs.
Number of lines to return. Defaults to 100.
If true, return the last N lines instead of the first N. Useful for checking recent log activity. Default: false.
Skip this many lines from the start (or from the end if tail=true). Use for pagination through large files.
Return only lines after this point in time. Accepts RFC3339 timestamps (2024-01-15T10:00:00Z) or relative durations (1h, 30m, 2h30m). Relative durations are resolved against the current server time.
Return only lines before this point in time. Same format as since.
path — file path that was read
lines — array of log lines (strings)
count — number of lines returned
Inputs: path (required), tail, lines, since, +2 more.
Search a log file for lines matching a regular expression. Returns matching lines with optional surrounding context.
Use when you need to find specific events, errors, or patterns in a log file without reading the whole file. More efficient than read_log for targeted searches. Combine with since/until to scope the search to a time window.
Absolute path to the log file. Obtain valid paths from list_logs.
Regular expression to search for. Uses Go regexp syntax. The pattern is not echoed back in the response.
Restrict the search to lines after this point in time. Accepts RFC3339 timestamps or relative durations (1h, 30m).
Restrict the search to lines before this point in time. Same format as since.
Maximum number of matching lines to return. Default: 200.
Number of surrounding lines to include before and after each match. Default: 0 (match lines only).
path — file path that was searched
pattern_redacted — always "<redacted>" (the search pattern is not echoed back for security reasons)
matches — array of match objects, each with:
line — the matching log line
line_number — 1-based line number in the file
context_before / context_after — surrounding lines (only present if context_lines > 0)
count — total number of matches returned
Inputs: path (required), pattern (required), since, until, +2 more.
Report the runtime status of this LogMCP server: whether the MCP layer is responding, how many tools are registered, and whether each configured extension is accessible.
Use as a first step when diagnosing MCP connectivity issues — before the deeper check_environment checks (file system, systemd, TLS). Returns quickly and confirms that the MCP tool layer itself is functional.
ok — true if all checks passed.
checks — array of check result objects, each with:
name — check identifier
ok — true if the check passed, false if it failed
detail — human-readable description of the result or error (omitted when empty)
Inputs: no named parameters.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 7 tools
Each tool has a clearly distinct purpose: configuration inspection, environment validation, log discovery, metadata retrieval, reading, searching, and server status. No overlap or ambiguity.
All tool names follow a consistent verb_noun pattern using snake_case (e.g., check_config, list_logs, read_log). No mixing of conventions.
With 7 tools, the set covers all core operations for a log management server without being excessive or sparse. Each tool earns its place.
The surface covers log discovery, reading, searching, metadata, and diagnostic checks. A minor gap is the lack of real-time tailing or streaming, but the set is otherwise complete for the intended purpose.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
