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.

License Node Version

✨ 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:

./logs (current directory)
./apps/backend/logs (monorepo structure)
./server/logs (server directory)
./backend/logs (backend directory)
/var/log (system logs on Linux/Mac)
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

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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

Install globally:
npm install -g local-logs-mcp-server
Add to
{ "mcpServers": { "local-logs": { "command": "local-logs-mcp", "env": { "LOGS_DIR": "./logs" } } } }
Restart Cursor and test:
- Ask: "Check my server logs"

Complete Claude Desktop Setup

Open Claude Desktop config:
# Mac open ~/Library/Application\ Support/Claude/claude_desktop_config.json # Windows notepad %APPDATA%\Claude\claude_desktop_config.json
Add configuration:
{ "mcpServers": { "local-logs": { "command": "npx", "args": ["-y", "local-logs-mcp-server"], "env": { "LOGS_DIR": "/Users/yourusername/projects/myapp/logs" } } } }
Restart Claude Desktop

🔗 Related Projects

Made with ❤️ for the MCP community

Deploy Server

HTTP connection URL

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Tools

Enables monitoring and analysis of local application log files with real-time tailing, error tracking, and search capabilities. Perfect for debugging Node.js applications, web servers, or any application that writes to log files through natural language commands.