Seq MCP Server

A Model Context Protocol (MCP) server that provides tools for searching and streaming events from Seq.

Installation

As a .NET Global Tool (Recommended)

# Install
dotnet tool install -g SeqMcpServer

# Update to latest version
dotnet tool update -g SeqMcpServer

# Uninstall
dotnet tool uninstall -g SeqMcpServer

Requirements

• .NET 10.0 Runtime or SDK
• Seq server (local or remote)
• Valid Seq API key

Quick Start

Development Environment

# Clone the repository
git clone https://github.com/willibrandon/seq-mcp-server
cd seq-mcp-server

# Setup development environment (fully automated)
# PowerShell (Windows)
./scripts/setup-dev.ps1

# Bash (Linux/Mac)
./scripts/setup-dev.sh

# Build and run the MCP server
dotnet build
dotnet run --project SeqMcpServer

The setup script automatically:

• Starts a Seq container on ports 15341/18081
• Configures authentication and creates an API key
• Sets up environment variables
• Creates a .env file for the application

Production Deployment

MCP servers are not run directly - they are launched by MCP clients. For production:

1. Build and deploy the executable:

dotnet publish -c Release -r win-x64 -p:PublishSingleFile=true

2. Configure your MCP client to use the deployed executable:

{
  "mcpServers": {
    "seq": {
      "command": "/path/to/seq-mcp-server",
      "env": {
        "SEQ_SERVER_URL": "http://your-seq-server:5341",
        "SEQ_API_KEY": "your-production-api-key"
      }
    }
  }
}

MCP Tools

The following tools are available through the MCP protocol:

• SeqSearch - Search Seq events with filters, date ranges, signals, and pagination

  • Parameters:
    • filter (required): Seq filter expression (use empty string "" for all events)
    • count: Number of events to return (default: 100, max: 1000)
    • signalId (optional): Signal ID to filter events (use SignalList to find IDs)
    • fromDateUtc (optional): Earliest date/time (ISO 8601, e.g., "2024-01-01T00:00:00Z")
    • toDateUtc (optional): Latest date/time (ISO 8601, e.g., "2024-01-31T23:59:59Z")
    • afterId (optional): Event ID to search after (exclusive) - use for pagination
    • timeoutSeconds (optional): Timeout in seconds (1-300)
    • workspace (optional): Specific workspace to query
  • Returns: List of matching events (ordered least to most recent)
  • Note: For date filtering, use fromDateUtc/toDateUtc parameters instead of @Timestamp in the filter expression for better performance
  • Pagination: To fetch more than 1000 events, use afterId with the ID of the last event from the previous search
  • Example filters:
    • "" - all events
    • "error" - events containing "error"
    • @Level = "Error" - error level events
    • Application = "MyApp" - events from specific application
  • Example with date range:
    • filter: "@Level = 'Error'", fromDateUtc: "2024-01-01T00:00:00Z", toDateUtc: "2024-01-31T23:59:59Z"
  • Example with pagination:
    • First call: filter: "", count: 1000 → returns events with IDs
    • Second call: filter: "", count: 1000, afterId: "event-<last-id>" → returns next batch

• SeqWaitForEvents - Wait for and capture live events from Seq (5-second timeout)

  • Parameters:
    • filter (optional): Seq filter expression
    • count: Number of events to capture (default: 10, max: 100)
    • workspace (optional): Specific workspace to query
  • Returns: Snapshot of events captured during the wait period (may be empty if no events match)

• SignalList - List available signals (read-only)

  • Parameters:
    • workspace (optional): Specific workspace to query
  • Returns: List of signals with their definitions

• SeqConvertFilter - Convert fuzzy filter to strict filter expression

  • Parameters:
    • fuzzyFilter (required): Fuzzy search text (e.g., "error", "timeout")
    • workspace (optional): Specific workspace to query
  • Returns: Strict Seq filter expression for use in SeqSearch
  • Use case: Help users write correct filter expressions
  • Example: Convert "error" to a proper Seq filter expression

Claude Desktop Integration

Option 1: Using .NET Global Tool (Recommended)

After installing the global tool, add to your Claude Desktop configuration:

{
  "mcpServers": {
    "seq": {
      "command": "seq-mcp-server",
      "env": {
        "SEQ_SERVER_URL": "http://localhost:5341",
        "SEQ_API_KEY": "your-api-key-here"
      }
    }
  }
}

Option 2: Pre-built Release

Download the latest release for your platform and add to your MCP settings:

{
  "mcpServers": {
    "seq": {
      "command": "C:\\\\Tools\\\\seq-mcp-server.exe",
      "args": [],
      "env": {
        "SEQ_SERVER_URL": "http://localhost:5341",
        "SEQ_API_KEY": "your-api-key-here"
      }
    }
  }
}

Option 3: Build from Source

Build a single-file executable (requires .NET 10 runtime):

# Windows
dotnet publish -c Release -r win-x64 -p:PublishSingleFile=true

# macOS
dotnet publish -c Release -r osx-x64 -p:PublishSingleFile=true

# Linux
dotnet publish -c Release -r linux-x64 -p:PublishSingleFile=true

The executable will be in SeqMcpServer/bin/Release/net10.0/{runtime}/publish/

Configuration

The Seq MCP Server uses environment variables for configuration:

• SEQ_SERVER_URL: URL of your Seq server
• SEQ_API_KEY: API key for accessing Seq (required)
• SEQ_API_KEY_<WORKSPACE>: Optional workspace-specific API keys (e.g., SEQ_API_KEY_PRODUCTION)

Seq Compatibility

SeqSearch prefers Events.EnumerateAsync(), which uses the Seq Scan link when the server advertises it. Older Seq builds such as 2024.3.x do not expose Scan on api/events/resources; in that case the server now falls back to PagedEnumerateAsync() so searches continue to work instead of failing with:

System.NotSupportedException: The requested link `Scan` isn't available on entity `Seq.Api.Model.ResourceGroup`.

If you are debugging compatibility issues:

• Seq 2025.2.x and newer expose Scan
• Seq 2024.3.x does not expose Scan
• this MCP server supports both paths by falling back automatically

Workspace Support

The MCP server supports workspace-specific API keys (future feature):

export SEQ_API_KEY="default-key"
export SEQ_API_KEY_PRODUCTION="production-key"
export SEQ_API_KEY_STAGING="staging-key"

Note: Workspace-specific keys are currently designed but not yet implemented in the MCP tools.

Development

Prerequisites

• .NET 10.0 SDK
• Docker (for running Seq locally)

Running Tests

dotnet test

Development

The scripts folder contains automated setup scripts:

• setup-dev.ps1 / setup-dev.sh: Automatically configures your development environment

  • Starts Seq container with authentication
  • Handles initial password setup
  • Creates development API key
  • Sets environment variables
  • Creates .env file for the application

• teardown-dev.ps1 / teardown-dev.sh: Cleans up the development environment

  • Stops and removes containers
  • Clears environment variables

For detailed development setup, see docs/DEVELOPMENT.md.

Architecture

This is a pure MCP server implementation that:

• Runs as a stdio-based service (no web server)
• Communicates via JSON-RPC over standard input/output
• Does not log to console to avoid interfering with MCP communication
• Optionally logs to Seq itself for debugging when configured

Self-Logging

The MCP server can log its own operations to Seq when a valid SEQ_SERVER_URL and SEQ_API_KEY are provided. This helps with debugging and monitoring the MCP server itself.

License

MIT License - see LICENSE file for details.