SEQ

You run an MCP server that lets large language models query and analyze logs from a SEQ structured logging deployment. It provides fast search, detailed event views, log analysis over time, access to saved signals, and a health check to verify connectivity with SEQ.

How to use

You connect a client to the MCP server either over HTTP to a remote SEQ-enabled endpoint or by running the MCP server locally as a stdio process. Once connected, you can search events, retrieve full event details, analyze patterns over time, list saved signals, and run health checks to ensure your setup can reach SEQ.

Practical usage patterns include:

• Searching for specific messages or levels across a time window
• Getting complete details for an event ID to investigate incidents
• Analyzing request patterns to identify slow paths or error bursts over configurable ranges
• Listing signals to reuse saved SEQ searches
• Running a health check to confirm connectivity to SEQ and to verify API key validity (when used)

How to install

Prerequisites: ensure you have Node.js 18 or newer and access to a SEQ server. If your SEQ instance requires authentication, obtain an API key.

# Option 1: Using Docker (recommended)
docker pull ghcr.io/roeej/seq-mcp:latest

# Or using Docker Hub
docker pull roeej/seq-mcp:latest

Additional setup steps

Optionally, set environment variables to point the MCP server at your SEQ instance. You can start with the defaults and override as needed.

cp .env.example .env

SEQ_URL=http://your-seq-server:5341
SEQ_API_KEY=your-api-key-here

If you prefer building from source, you can install dependencies and build the project.

## Configuration

Environment variables you can configure for the MCP server are shown here. These control where SEQ is reached, how long to wait, and how many events are returned by default.

SEQ_URL=http://localhost:5341 SEQ_API_KEY=your-api-key-here SEQ_DEFAULT_LIMIT=100 SEQ_TIMEOUT=30000

## Security and best practices

- API keys are used for authentication when your SEQ instance requires it. Treat keys as secrets and do not log them.

- Use read-only API keys to prevent log modification. Ensure network access is restricted to trusted applications.

- Enable TLS/HTTPS if you expose the MCP server over untrusted networks.

## Troubleshooting

If you cannot reach SEQ or run into timeouts, verify the following:
- SEQ is running and reachable at the SEQ\_URL you configured
- Your API key (if used) has the appropriate permissions
- Network connectivity allows the MCP server to reach the SEQ instance
- If you see timeout errors, increase SEQ\_TIMEOUT to accommodate longer queries

## Example usage concepts

Common tasks you can perform include filtering by log level or message content, filtering by date range, and retrieving structured details for investigation. You can also analyze patterns across time ranges and compare signals to identify recurring issues.

## Available tools

### search\_events

Search for events with filters such as level, message content, and time range using SEQ filter syntax.

### get\_event

Retrieve detailed information about a specific event by its ID.

### analyze\_logs

Analyze log patterns over a specified time range and optionally group results by a property.

### list\_signals

List saved signals (configured searches) in SEQ.

### check\_health

Check the health status of the connected SEQ server.