Seq MCP Server

Pesquise e transmita eventos de um servidor Seq.

GitHub
22
Experimente este MCPPatrocinado

Documentação

Seq MCP Server

Um servidor Model Context Protocol (MCP) que fornece ferramentas para pesquisar e transmitir eventos do Seq.

Instalação

Como uma Ferramenta Global .NET (Recomendado)

# Install
dotnet tool install -g SeqMcpServer

# Update to latest version
dotnet tool update -g SeqMcpServer

# Uninstall
dotnet tool uninstall -g SeqMcpServer

Requisitos

  • Runtime ou SDK .NET 10.0
  • Servidor Seq (local ou remoto)
  • Chave de API Seq válida

Início Rápido

Ambiente de Desenvolvimento

# 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

O script de configuração automaticamente:

  • Inicia um contêiner Seq nas portas 15341/18081
  • Configura autenticação e cria uma chave de API
  • Define variáveis de ambiente
  • Cria um arquivo .env para a aplicação

Implantação em Produção

Servidores MCP não são executados diretamente - eles são iniciados por clientes MCP. Para produção:

  1. Compile e implante o executável:
dotnet publish -c Release -r win-x64 -p:PublishSingleFile=true
  1. Configure seu cliente MCP para usar o executável implantado:
{
  "mcpServers": {
    "seq": {
      "command": "/path/to/seq-mcp-server",
      "env": {
        "SEQ_SERVER_URL": "http://your-seq-server:5341",
        "SEQ_API_KEY": "your-production-api-key"
      }
    }
  }
}

Ferramentas MCP

As seguintes ferramentas estão disponíveis através do protocolo MCP:

  • SeqSearch - Pesquisar eventos Seq com filtros, intervalos de datas, sinais e paginação

    • Parâmetros:
      • filter (obrigatório): Expressão de filtro Seq (use string vazia "" para todos os eventos)
      • count: Número de eventos a retornar (padrão: 100, máximo: 1000)
      • signalId (opcional): ID do sinal para filtrar eventos (use SignalList para encontrar IDs)
      • fromDateUtc (opcional): Data/hora mais antiga (ISO 8601, ex.: "2024-01-01T00:00:00Z")
      • toDateUtc (opcional): Data/hora mais recente (ISO 8601, ex.: "2024-01-31T23:59:59Z")
      • afterId (opcional): ID do evento para pesquisar após (exclusivo) - use para paginação
      • timeoutSeconds (opcional): Tempo limite em segundos (1-300)
      • workspace (opcional): Workspace específico para consultar
    • Retorna: Lista de eventos correspondentes (ordenados do menos recente para o mais recente)
    • Nota: Para filtragem por data, use os parâmetros fromDateUtc/toDateUtc em vez de @Timestamp na expressão de filtro para melhor desempenho
    • Paginação: Para buscar mais de 1000 eventos, use afterId com o ID do último evento da pesquisa anterior
    • Exemplos de filtros:
      • "" - todos os eventos
      • "error" - eventos contendo "error"
      • @Level = "Error" - eventos de nível de erro
      • Application = "MyApp" - eventos de aplicação específica
    • Exemplo com intervalo de datas:
      • filter: "@Level = 'Error'", fromDateUtc: "2024-01-01T00:00:00Z", toDateUtc: "2024-01-31T23:59:59Z"
    • Exemplo com paginação:
      • Primeira chamada: filter: "", count: 1000 → retorna eventos com IDs
      • Segunda chamada: filter: "", count: 1000, afterId: "event-<last-id>" → retorna o próximo lote

  • SeqWaitForEvents - Aguardar e capturar eventos ao vivo do Seq (tempo limite de 5 segundos)

    • Parâmetros:
      • filter (opcional): Expressão de filtro Seq
      • count: Número de eventos a capturar (padrão: 10, máximo: 100)
      • workspace (opcional): Workspace específico para consultar
    • Retorna: Instantâneo dos eventos capturados durante o período de espera (pode estar vazio se nenhum evento corresponder)

  • SignalList - Listar sinais disponíveis (somente leitura)

    • Parâmetros:
      • workspace (opcional): Workspace específico para consultar
    • Retorna: Lista de sinais com suas definições

  • SeqConvertFilter - Converter filtro difuso em expressão de filtro estrita

    • Parâmetros:
      • fuzzyFilter (obrigatório): Texto de pesquisa difusa (ex.: "error", "timeout")
      • workspace (opcional): Workspace específico para consultar
    • Retorna: Expressão de filtro Seq estrita para uso em SeqSearch
    • Caso de uso: Ajudar usuários a escrever expressões de filtro corretas
    • Exemplo: Converter "error" em uma expressão de filtro Seq adequada

Integração com Claude Desktop

Opção 1: Usando Ferramenta Global .NET (Recomendado)

Após instalar a ferramenta global, adicione à sua configuração do Claude Desktop:

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

Opção 2: Versão Pré-compilada

Baixe a versão mais recente para sua plataforma e adicione às suas configurações MCP:

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

Opção 3: Compilar a partir do Código Fonte

Compile um executável de arquivo único (requer runtime .NET 10):

# 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

O executável estará em SeqMcpServer/bin/Release/net10.0/{runtime}/publish/

Configuração

O Seq MCP Server usa variáveis de ambiente para configuração:

  • SEQ_SERVER_URL: URL do seu servidor Seq
  • SEQ_API_KEY: Chave de API para acessar o Seq (obrigatória)
  • SEQ_API_KEY_<WORKSPACE>: Chaves de API opcionais específicas de workspace (ex.: SEQ_API_KEY_PRODUCTION)

Compatibilidade com Seq

SeqSearch prefere Events.EnumerateAsync(), que usa o link Scan do Seq quando o servidor o anuncia. Versões mais antigas do Seq, como 2024.3.x, não expõem Scan em api/events/resources; nesse caso, o servidor agora usa PagedEnumerateAsync() como fallback para que as pesquisas continuem funcionando em vez de falhar com:

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

Se você estiver depurando problemas de compatibilidade:

  • Seq 2025.2.x e mais recentes expõem Scan
  • Seq 2024.3.x não expõe Scan
  • este servidor MCP suporta ambos os caminhos com fallback automático

Suporte a Workspace

O servidor MCP suporta chaves de API específicas de workspace (recurso futuro):

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

Nota: Chaves específicas de workspace estão atualmente projetadas, mas ainda não implementadas nas ferramentas MCP.

Desenvolvimento

Pré-requisitos

  • SDK .NET 10.0
  • Docker (para executar Seq localmente)

Executando Testes

dotnet test

Desenvolvimento

A pasta scripts contém scripts de configuração automatizados:

  • setup-dev.ps1 / setup-dev.sh: Configura automaticamente seu ambiente de desenvolvimento

    • Inicia contêiner Seq com autenticação
    • Gerencia configuração inicial de senha
    • Cria chave de API de desenvolvimento
    • Define variáveis de ambiente
    • Cria arquivo .env para a aplicação

  • teardown-dev.ps1 / teardown-dev.sh: Limpa o ambiente de desenvolvimento

    • Para e remove contêineres
    • Limpa variáveis de ambiente

Para configuração detalhada de desenvolvimento, veja docs/DEVELOPMENT.md.

Arquitetura

Esta é uma implementação pura de servidor MCP que:

  • Executa como um serviço baseado em stdio (sem servidor web)
  • Comunica via JSON-RPC sobre entrada/saída padrão
  • Não registra logs no console para evitar interferência com a comunicação MCP
  • Opcionalmente registra logs no próprio Seq para depuração quando configurado

Auto-registro de Logs

O servidor MCP pode registrar suas próprias operações no Seq quando um SEQ_SERVER_URL e SEQ_API_KEY válidos são fornecidos. Isso ajuda na depuração e monitoramento do próprio servidor MCP.

Licença

Licença MIT - veja o arquivo LICENSE para detalhes.