Local Logs MCP Server

A Model Context Protocol (MCP) server for monitoring local application logs with real-time tailing, error tracking, and log search capabilities.

Perfect for monitoring Node.js applications, web servers, or any application that writes to log files.

✨ Features

• 📁 Log File Discovery - Automatically finds and lists available log files
• 📜 Real-time Log Tailing - Get the last N lines from any log file
• ⚠️ Error Monitoring - Quickly check error logs for issues
• 📊 Server Status - Get server status summary from log analysis
• 👀 Log Watching - Monitor log files for changes
• 🔍 Log Search - Search 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

🛠️ Available Tools

Tool	Description	Parameters
get_log_files	List available log files with metadata	None
tail_log	Get last N lines from a log file	filename, lines
get_errors	Get recent error log entries	lines
get_server_status	Server status summary from logs	None
watch_log	Monitor log file for changes	filename
search_logs	Search for text in log files	query, filename, lines

📦 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 download the server file directly and configure Cursor automatically. 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 .

⚙️ Configuration

✅ Automatic Configuration (Default)

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

🔧 Manual Configuration (If needed)

For Cursor IDE

Add 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 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 to your .vscode/mcp.json:

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

For Windsurf (Codium)

Add to your Windsurf MCP config:

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

🔧 Environment Variables

Variable	Description	Default
LOGS_DIR	Directory containing log files	Auto-detected (see below)
LOG_EXTENSIONS	Comma-separated log file extensions	.log,.txt

Log Directory Auto-Detection

If LOGS_DIR is not specified, the server automatically searches for logs in this 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

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

Basic Commands

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

Advanced Commands

• "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 - Server only reads log files, never writes or modifies
• Directory scoping - Only accesses files in the specified logs directory
• No network access - Operates entirely on local files
• Permission respect - Respects file system permissions

🚀 Performance

• Efficient file reading - Uses streaming for large log files
• Memory conscious - Doesn't load entire files into memory
• Fast search - 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 log files have proper read permissions
• Ensure 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 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 LOG_EXTENSIONS setting
• Verify 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