# 🚀 Log Reader Mcp
[](https://opensource.org/licenses/MIT)
> 🚀 **Stop wasting time copy-pasting logs!**<br>
> 🧠 **Let Cursor's AI instantly access, search, and explain your logs — no more manual work, just answers.**
## 📚 Table of Contents
- [Why Log Reader Mcp?](#-why-log-reader-mcp)
- [Installation](#-installation)
- [Automatic (recommended)](#-automatic-recommended)
- [Manual](#-manual)
- [Who is it for?](#-who-is-it-for)
- [MCP Configuration](#-mcp-configuration)
- [Example Prompts for Cursor](#-example-prompts-for-cursor)
- [CLI Usage](#-cli-usage)
- [Log Format (JSON per line)](#-log-format-json-per-line)
- [Developer Guide](#-developer-guide)
- [Key Advantages](#-key-advantages)
- [FAQ](#-faq)
- [Getting Help](#-getting-help)
- [Contributing](#-contributing)
- [License](#-license)
- [Cursor Rule (Workflow)](#-cursor-rule-workflow)
---
## ✨ Why Log Reader Mcp?
- 🤖 **AI-powered log access**: Give your AI assistant (Cursor, etc.) direct, on-demand access to your app logs.
- 🧠 **Smarter debugging**: Let the AI analyze, summarize, and explain logs as you code.
- ⏱️ **Save hours**: No more switching terminals, tailing files, or hunting for errors—get instant feedback and context.
- 🛡️ **Safe & isolated**: Never pollutes your project, robust CLI and test coverage.
- ⚡ **Plug & Play**: One command, zero config, works everywhere.
---
## 👤 Who is it for?
- Backend & frontend developers
- DevOps & SREs
- Teams using AI-powered editors (Cursor, etc.)
- Anyone who wants faster, smarter log analysis!
---
## 📦 Installation
### 🚀 Automatic (recommended)
```sh
npx log-reader-mcp init
```
- Installs everything, creates `.cursor/mcp.json` and workflow rules, and sets up your logs folder automatically.
### 🛠️ Manual
1. **Install the package**
```sh
npm install --save-dev log-reader-mcp
```
2. **Create the config file**
- At the root of your project, create a folder named `.cursor` (if it doesn't exist).
- Inside `.cursor/`, create a file named `mcp.json` with:
```json
{
"mcpServers": {
"log-reader-mcp": {
"command": "npx",
"args": ["-y", "log-reader-mcp"]
}
},
"mcp.enabled": true,
"mcp.autoStart": true,
"mcp.showStatusBar": true,
"mcp.logLevel": "info"
}
```
- This tells your editor (Cursor, VSCode, etc.) how to launch and connect to the log reader mcp server for your project.
---
## 🖼️ What does it do?
**Log Reader Mcp** exposes your application's logs to your AI assistant/editor (like Cursor) via the Model Control Protocol (MCP). This means:
- The AI can read, filter, and analyze your logs on demand (not streaming)
- You can ask the AI to fetch logs for a specific period, number of lines, error level, etc.
- Makes onboarding, debugging, and incident response dramatically faster
### 🔧 Key Features
- **Simplified Interface**: No `logPath` parameter needed - always uses `logs/logs.log` in your working directory
- **Automatic Detection**: The server automatically finds and reads your log file
- **Time-based Filtering**: Filter logs by specific time ranges using ISO 8601 format
- **Line-based Reading**: Read the last N lines with automatic validation
- **Structured JSON**: Full support for structured logging with metadata
---
## 💡 Example Prompts for Cursor
Here are some real-world prompts you can use in Cursor (or any MCP-enabled AI) to interact with your logs:
| Use Case | Example Prompt to Cursor AI |
| ------------------ | ----------------------------------------------------------- |
| 🔢 Last N logs | `Show me the last 100 log entries` |
| 🕒 Logs by time | `Get all logs between 2024-06-01 and 2024-06-02` |
| ⏩ Logs since date | `Show all logs since 2024-06-01` |
| 🚨 Errors only | `Show only ERROR or CRITICAL logs from the last 50 entries` |
| 🔍 Search message | `Find all logs containing "database connection failed"` |
| 🧑💻 User-specific | `Show all logs for user_id 12345 in the last 24 hours` |
| 📊 Summary | `Summarize the main issues found in today's logs` |
| 🧹 Clear context | `Clear the log context and start a new analysis` |
> **Note:** The tool automatically uses `logs/logs.log` in your current working directory. The `logPath` parameter has been removed for maximum simplicity - no need to specify any file path!
> **Tip:** You can combine filters, time ranges, and keywords in your prompts. The AI will use Log Reader Mcp to fetch and analyze the relevant log data for you!
---
## 💡 Use Cases
| Use Case | How Log Reader Mcp Helps | Time Saved |
| ---------------------- | ----------------------------------------------------------- | ------------------ |
| 🐞 Real-time debugging | See errors & warnings instantly in Cursor, with AI context | Minutes per bug |
| 🔍 AI log analysis | Let the AI summarize, filter, and explain log events | Hours per incident |
| 🚦 Incident response | Quickly surface critical issues to the whole team | Days per outage |
| 👩💻 Onboarding | New devs get instant, readable log feedback in their editor | Weeks per new hire |
| 📊 Audit & compliance | Structured logs, easy to export and review | Countless hours |
---
## ⚙️ MCP Configuration Example
```json
{
"mcpServers": {
"log-reader-mcp": {
"command": "npx",
"args": ["-y", "log-reader-mcp"]
}
},
"mcp.enabled": true,
"mcp.autoStart": true,
"mcp.showStatusBar": true,
"mcp.logLevel": "info"
}
```
- 📁 Place this in `.cursor/mcp.json`
- Your editor will auto-detect and use the log server
---
## 🖥️ CLI Usage
| Command | Effect |
| --------------------------------- | --------------------------------------- |
| `npx log-reader-mcp init` | Initialize MCP config and log workflow |
| `npx log-reader-mcp -h/--help` | Show help and CLI options |
| `npx log-reader-mcp -v/--version` | Show the current package version |
| `npx log-reader-mcp` | Start the MCP log server (default mode) |
---
## 📝 Log Format (JSON per line)
Each line in `logs/logs.log` should be a JSON object:
```json
{
"level": "INFO|WARN|ERROR|DEBUG|CRITICAL",
"timestamp": "2024-06-01T12:34:56.789Z",
"message": "User login succeeded",
"service_name": "auth",
"user_id": "12345",
"context": { "ip": "192.168.1.10" },
"event": { "action": "login" }
}
```
---
## 🧑💻 Developer Guide
- **Release & Versioning**: Automated with semantic-release, changelog, and version auto-sync
- **CI/CD**: GitHub Actions (`.github/workflows/`)
- **Testing**: 100% coverage, CLI test isolation, robust integration
- **Project Structure**:
- `src/` — TypeScript sources
- `bin/cli.js` — CLI entry point
- `templates/` — MCP config & workflow templates
- `.github/workflows/` — CI/CD
---
## 🏆 Key Advantages
- 🔒 **Zero config, zero risk**: Never pollutes your project
- 🧪 **100% tested**: Full test isolation, robust CI
- 🏗️ **AI-ready**: Structured logs, perfect for automated analysis
- 🚀 **Plug & Play**: Works with all MCP editors, no setup required
- ⏳ **Massive time savings**: Focus on code, not on chasing logs
---
## 🤝 Contributing
1. Fork & create a branch
2. Use conventional commits
3. `npm run build` to compile
4. `npm test` to verify
5. Open a clear, detailed PR
---
## 📄 License
MIT
---
## 📝 Cursor Rule (Workflow)
To help Cursor (or any MCP-compatible AI) understand your log structure and best practices, you can add a workflow rule file:
### How to add the Cursor rule
1. **Copy the template**
- Use the command: `npx log-reader-mcp init` (recommended)
- Or manually copy `templates/mcp-log-server/workflow.mdc` to `.cursor/log-reader-mcp/workflow.mdc` at the root of your project.
2. **What does this rule do?**
- It describes the log file location, format, and usage standards for your project.
- It helps the AI agent (Cursor, etc.) understand how to read, filter, and analyze your logs.
- It documents best practices for logging, security, and debugging for your team.
### Example (excerpt)
```yaml
---
description: Guide for using log-reader-mcp
globs: **/*
alwaysApply: true
---
# MCP Logging Workflow
- Log folder: `logs/`
- Log file: `logs.log` (one JSON object per line)
- Example log entry:
{
"level": "INFO",
"timestamp": "2024-06-01T12:34:56.789Z",
"message": "User login succeeded",
...
}
- Use the `read_log` tool to fetch logs by line count or time range
- Never include sensitive data in logs
- Always validate log format before writing
```
### Why add this rule?
- 🧠 **For the AI**: It enables Cursor to provide smarter, context-aware log analysis and suggestions.
- 👩💻 **For developers**: It ensures everyone follows the same standards and makes onboarding easier.
- 🔒 **For security**: It reminds everyone not to log sensitive data and to validate log structure.
> **Tip:** Keeping this rule up to date helps both humans and AI work better with your logs!
---
## ❓ FAQ
**Q: Is it compatible with VSCode or only Cursor?**
A: Any editor supporting MCP can use it, including Cursor and future tools.
**Q: Can I use multiple MCP servers?**
A: Yes, just add more entries in `.cursor/mcp.json`.
**Q: What log formats are supported?**
A: Only structured JSON logs (one object per line) are supported for full AI analysis.
**Q: Is it safe for production?**
A: Yes! The tool never modifies your logs, only reads them, and is fully tested.
---
## 💬 Getting Help
- Open an [issue](https://github.com/hassansaadfr/log-reader-mcp/issues) for bugs or questions
- Join the discussion on [GitHub Discussions](https://github.com/hassansaadfr/log-reader-mcp/discussions)
- See the [Cursor Rule Template](./templates/mcp-log-server/workflow.mdc) for advanced configuration
---
