log-reader-mcp
MCP server for Claude Code — lets Claude start, monitor, search, and detect errors in logs from any project, even ones that don't write log files.
Requirements: Python 3.8+, Claude Code
---
Install (one-line, any machine)
SSH (if you have GitHub SSH keys set up): ``bash git clone git@github.com:ankit-jhajhria/log-reader-mcp.git ~/.claude/mcp-servers/log-reader && bash ~/.claude/mcp-servers/log-reader/setup.sh ``
HTTPS (works without SSH keys): ``bash git clone https://github.com/ankit-jhajhria/log-reader-mcp.git ~/.claude/mcp-servers/log-reader && bash ~/.claude/mcp-servers/log-reader/setup.sh ``
Restart Claude Code after install.
Ubuntu/Debian users: If setup fails with a
venverror, runsudo apt install python3-venvfirst — the script will tell you this too.
---
How to use in a new session
Project with no log files — Option A: tmux (you see it running)
Start your terminal inside tmux once: ``bash tmux new -s myserver ``
Then tell Claude: `` run "docker compose up --build" in my tmux session "myserver" ``
Claude sends the command to your terminal — you watch it run. To stop: `` stop docker in tmux session "myserver" ``
Claude sends Ctrl+C to the pane. You see it stop in real time.
---
Project with no log files — Option B: background (hidden, no terminal needed)
Open Claude Code in your project and say:
run "node server.js" and capture the logsClaude starts the server in the background, captures all terminal output, and tails the log immediately. Always set the working directory so the command runs from the right folder:
run "npm start" in /home/user/my-node-project and capture the logsTo check for problems: `` detect errors in the captured log ``
To restart after a code change: `` restart the server ``
To stop it: `` stop the server ``
---
Project that already writes log files (Django, Rails, etc.)
tail logs/debug.logdetect errors in logs/debug.logsearch logs/debug.log for "Traceback" with 3 lines of contextshow me new lines in logs/debug.log since line 400---
Don't know where the logs are
list log files in the logs folderFiles modified in the last 60 seconds are marked [active] so you can spot the right one instantly.
---
All tools
tmux — direct terminal control (no log files needed)
| Tool | What it does | |---|---| | tmux_sessions() | List all running tmux sessions and panes | | tmux_new_session(session, command, cwd) | Create a new tmux session, optionally run a command in it | | tmux_run(session, command, pane, wait) | Send a command to a tmux pane — runs visibly in your terminal | | tmux_read(session, pane, lines) | Read output directly from a tmux pane — no log file needed | | tmux_send_keys(session, keys) | Send raw keys like Ctrl+C, Ctrl+D, Enter to stop/control processes |
Process management (background — no visible terminal)
| Tool | What it does | |---|---| | run_and_capture(command, cwd, log_file) | Start any server in background, capture all output to a file | | list_captured_processes() | Show all running/stopped captured processes | | stop_process(pid) | Stop a process | | restart_process(pid) | Stop and restart with the same command and working directory |
Log reading
| Tool | What it does | |---|---| | detect_errors(path, last_lines) | Auto-scan for ERROR, Exception, Traceback, WARNING, CRITICAL, fatal | | tail_file(path, lines=80) | Last N lines of any log file | | get_new_lines(path, after_line) | New lines since line N — use to poll a running server | | search_log(path, pattern, context_lines) | Regex/string search with optional surrounding context lines | | list_log_files(directory, pattern) | List log files with sizes and active status | | file_info(path) | Size, modified time, line count |
---
Troubleshooting
python3-venv error on Ubuntu/Debian: ``bash sudo apt install python3-venv ``
Permission denied reading a log file: Some system logs (e.g. /var/log/syslog) require elevated permissions. Run Claude Code with sudo or copy the log to a readable location.
Process exits immediately after run_and_capture: The tool detects this and shows you the output. Common causes: wrong command, port already in use, missing dependencies. Fix the command and try again.
