Local Logs MCP Server

🚀 Local Logs MCP Server

A Model Context Protocol (MCP) server that enables real - time tailing, error tracking, and log search for monitoring local application logs. Ideal for monitoring Node.js applications, web servers, or any application that writes to log files.

🚀 Quick Start

This Local Logs MCP Server allows you to conveniently monitor local application logs. After installation and configuration, you can use natural language commands to interact with it.

✨ Features

• 📁 Log File Discovery: Automatically discovers and lists available log files.
• 📜 Real - time Log Tailing: Retrieves the last N lines from any log file.
• ⚠️ Error Monitoring: Quickly checks error logs for issues.
• 📊 Server Status: Obtains a server status summary through log analysis.
• 👀 Log Watching: Monitors log files for changes.
• 🔍 Log Search: Searches for specific text patterns in logs.
• 🔧 Configurable: Supports custom log directories and file extensions.
• 🚀 Easy Setup: Works with Cursor, Claude Desktop, VS Code Copilot, and more.

📦 Installation

🚀 One - Command Setup (Recommended)

Linux/Mac:

curl -sSL https://raw.githubusercontent.com/mariosss/local-logs-mcp-server/main/install-new.js | node

Windows (PowerShell):

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/mariosss/local-logs-mcp-server/main/install-new.js" | Invoke-Expression

That's it! The installation script will directly download the server file and automatically configure Cursor. Just restart Cursor and you're ready to go!

Alternative: Two - Command Setup

npm install -g https://github.com/mariosss/local-logs-mcp-server
local-logs-setup

Alternative: Manual Setup

npm install -g local-logs-mcp-server
local-logs-setup

NPX Usage (No Installation)

npx local-logs-mcp-server

Manual Installation

git clone https://github.com/mariosss/local-logs-mcp-server.git
cd local-logs-mcp-server
npm install -g .

🛠️ Available Tools

⚙️ Configuration

✅ Automatic Configuration (Default)

The package automatically configures Cursor for you! No manual setup is required.

🔧 Manual Configuration (If needed)

For Cursor IDE

Add the following to your .cursor/mcp.json (project - specific) or global MCP config:

{
  "mcpServers": {
    "local-logs": {
      "command": "npx",
      "args": ["-y", "local-logs-mcp-server"],
      "env": {
        "LOGS_DIR": "./logs"
      }
    }
  }
}

For Claude Desktop

Add the following to your Claude Desktop MCP config (~/Library/Application Support/Claude/claude_desktop_config.json on Mac):

{
  "mcpServers": {
    "local-logs": {
      "command": "npx",
      "args": ["-y", "local-logs-mcp-server"],
      "env": {
        "LOGS_DIR": "/path/to/your/logs"
      }
    }
  }
}

For VS Code (GitHub Copilot)

Add the following to your .vscode/mcp.json:

{
  "servers": {
    "local-logs": {
      "command": "npx",
      "args": ["-y", "local-logs-mcp-server"],
      "env": {
        "LOGS_DIR": "./logs"
      }
    }
  }
}

For Windsurf (Codium)

Add the following to your Windsurf MCP config:

{
  "mcpServers": {
    "local-logs": {
      "command": "npx",
      "args": ["-y", "local-logs-mcp-server"],
      "env": {
        "LOGS_DIR": "./logs"
      }
    }
  }
}

🔧 Environment Variables

Log Directory Auto - Detection

If LOGS_DIR is not specified, the server automatically searches for logs in the following priority order:

1. ./logs (current directory)
2. ./apps/backend/logs (monorepo structure)
3. ./server/logs (server directory)
4. ./backend/logs (backend directory)
5. /var/log (system logs on Linux/Mac)
6. C:\logs (system logs on Windows)

💻 Usage Examples

Basic Usage

Once configured with your MCP client, you can use the following natural language commands:

• "Check my server logs"
• "Are there any errors in the logs?"
• "What's my server status?"
• "Show me available log files"

Advanced Usage

• "Show me the last 50 lines from error.log"
• "Search logs for 'database connection'"
• "Monitor access.log for changes"
• "Find all log entries containing 'TypeError'"

🏗️ Project Structure Examples

Standard Node.js Project

your-project/
├── logs/
│   ├── combined.log    # Main application log
│   ├── error.log      # Error log
│   └── access.log     # Access log (optional)
├── .cursor/
│   └── mcp.json       # MCP configuration
├── src/
└── package.json

Monorepo Structure

your-monorepo/
├── apps/
│   └── backend/
│       └── logs/
│           ├── combined.log
│           └── error.log
├── .cursor/
│   └── mcp.json
└── package.json

🔍 Supported Log Formats

The server works with any text - based log files and can parse:

• Winston logs (JSON and text format)
• Morgan access logs
• Pino logs
• Bunyan logs
• Custom application logs
• System logs
• Any .log or .txt files

Example Log Formats

Winston Text Format:

2024-01-15 10:30:45 [INFO]: Server started on port 3000
2024-01-15 10:30:50 [ERROR]: Database connection failed

Winston JSON Format:

{"level":"info","message":"Server started","timestamp":"2024-01-15T10:30:45.123Z"}
{"level":"error","message":"Database connection failed","timestamp":"2024-01-15T10:30:50.456Z"}

🛡️ Security

• Read - only access: The server only reads log files and never writes or modifies them.
• Directory scoping: It only accesses files in the specified logs directory.
• No network access: It operates entirely on local files.
• Permission respect: It respects file system permissions.

🚀 Performance

• Efficient file reading: Uses streaming for large log files.
• Memory conscious: Does not load entire files into memory.
• Fast search: Utilizes optimized text search algorithms.
• Minimal dependencies: Only uses Node.js built - in modules.

🤝 Contributing

1. Fork the repository.
2. Create your feature branch (git checkout -b feature/amazing - feature).
3. Commit your changes (git commit -m 'Add amazing feature').
4. Push to the branch (git push origin feature/amazing - feature).
5. Open a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🐛 Troubleshooting

Server shows red/error status

• Check that the logs directory exists and is accessible.
• Verify that log files have proper read permissions.
• Ensure that the Node.js version is 14 or higher.
• Check that the server path is correct in your MCP config.

No tools available

• Restart your MCP client (Cursor, Claude, VS Code).
• Verify that the MCP configuration syntax is valid JSON.
• Check that the MCP server is responding (test with echo '{"jsonrpc":"2.0","method":"initialize","id":1}' | npx local-logs-mcp-server).

Log files not found

• Set the correct LOGS_DIR environment variable.
• Make sure your application is actually writing to log files.
• Check that file extensions match the LOG_EXTENSIONS setting.
• Verify that directory permissions allow reading.

Common Log Directory Issues

Issue: "Logs directory not found"

# Solution: Set explicit path
export LOGS_DIR="/path/to/your/logs"

Issue: "No log files found"

# Solution: Check file extensions
export LOG_EXTENSIONS=".log,.txt,.out"

📚 Examples

Complete Cursor Setup

1. Install globally:

npm install -g local-logs-mcp-server

2. Add to .cursor/mcp.json:

{
  "mcpServers": {
    "local-logs": {
      "command": "local-logs-mcp",
      "env": {
        "LOGS_DIR": "./logs"
      }
    }
  }
}

3. Restart Cursor and test: Ask: "Check my server logs"

Complete Claude Desktop Setup

1. Open Claude Desktop config:

# Mac
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Windows
notepad %APPDATA%\Claude\claude_desktop_config.json

2. Add configuration:

{
  "mcpServers": {
    "local-logs": {
      "command": "npx",
      "args": ["-y", "local-logs-mcp-server"],
      "env": {
        "LOGS_DIR": "/Users/yourusername/projects/myapp/logs"
      }
    }
  }
}

3. Restart Claude Desktop

🔗 Related Projects

• Supabase MCP Server
• Model Context Protocol
• MCP Servers Collection
• Cursor IDE
• Claude Desktop

Made with ❤️ for the MCP community