Skip to main content
Glama
itachiuchihadev

Seq MCP Server

Seq MCP Server (@abhishekkumar00019/seq-mcp)

npm version License: MIT

A Model Context Protocol (MCP) server and TypeScript library for Datalust Seq structured logging.

Enable AI assistants (Claude, Cursor, Copilot, ChatGPT, etc.) to query structured events, search logs by date ranges and signal filters, convert natural language filters into strict Seq syntax, execute analytical SQL queries, and monitor live log streams.


๐Ÿš€ Quick Start

Run instantly without installation using npx:

npx @abhishekkumar00019/seq-mcp

Or install globally:

npm install -g @abhishekkumar00019/seq-mcp
seq-mcp --help

Related MCP server: MCP Graylog Server

๐Ÿ› ๏ธ MCP Client Configuration

Claude Desktop

Add seq to your Claude Desktop configuration (claude_desktop_config.json):

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "seq": {
      "command": "npx",
      "args": ["-y", "--silent", "@abhishekkumar00019/seq-mcp"],
      "env": {
        "SEQ_SERVER_URL": "http://localhost:5341",
        "SEQ_API_KEY": "your-seq-api-key"
      }
    }
  }
}

Note: The --silent flag prevents npm/npx from printing command banner headers to stdout, ensuring clean JSON-RPC protocol communication over stdio.

Cursor IDE

In Cursor Settings โ†’ Features โ†’ MCP Servers โ†’ Add New MCP Server:

  • Name: seq

  • Type: command

  • Command: npx -y --silent @abhishekkumar00019/seq-mcp

Or configure via .cursor/mcp.json:

{
  "mcpServers": {
    "seq": {
      "command": "npx",
      "args": ["-y", "--silent", "@abhishekkumar00019/seq-mcp"],
      "env": {
        "SEQ_SERVER_URL": "http://localhost:5341",
        "SEQ_API_KEY": "your-seq-api-key"
      }
    }
  }
}

โš™๏ธ Configuration & Environment Variables

Variable

CLI Flag

Description

Default

SEQ_SERVER_URL

-u, --url

Base URL of the Seq server

http://localhost:5341

SEQ_API_KEY

-k, --api-key

Seq API Key for authentication

(empty)

SEQ_WORKSPACE

-w, --workspace

Default workspace identifier

default

SEQ_SECRETS_PATH

-s, --secrets

Path to secrets.json for multi-tenant workspace keys

secrets.json

SEQ_TIMEOUT_MS

-

Request timeout in milliseconds

30000

SEQ_MCP_LOG_LEVEL

-l, --log-level

Log level (debug, info, warn, error, silent)

info

Multi-Tenant Workspaces (secrets.json)

For multi-tenant environments with different API keys per workspace, place a secrets.json file in your workspace or specify --secrets /path/to/secrets.json:

{
  "default": "API_KEY_DEFAULT",
  "production": "API_KEY_PRODUCTION",
  "staging": "API_KEY_STAGING"
}

๐Ÿงฐ Available MCP Tools

1. seq_search

Search historical events with filters, ISO 8601 date ranges, signals, and pagination.

  • Parameters:

    • filter (string, optional): Seq filter expression (e.g. @Level = 'Error', Application = 'BillingService' and StatusCode >= 500). Defaults to "" or * (all events).

    • count (integer, optional, default: 100, max: 1000): Maximum number of events to return.

    • fromDateUtc (string, optional): Earliest date/time in ISO 8601 format (e.g., 2024-01-01T00:00:00Z).

    • toDateUtc (string, optional): Latest date/time in ISO 8601 format (e.g., 2024-01-31T23:59:59Z).

    • signalId (string, optional): Signal ID to filter events.

    • afterId (string, optional): Event ID to search after (exclusive) for pagination.

    • workspace (string, optional): Workspace identifier.

  • Example prompts for AI:

    • "Show me all Error events from the last 2 hours"

    • "Search for payment failure logs in Seq between 2026-10-15T00:00:00Z and 2026-10-16T00:00:00Z"


2. seq_query

Execute analytical SQL-like queries against Seq log data.

  • Parameters:

    • query (string, required): Seq SQL query (e.g., select count(*) from stream group by time(5m), select @Timestamp, @Message, @Level from stream where @Level = 'Error' limit 50).

    • fromDateUtc (string, optional): Start time boundary in ISO 8601 format.

    • toDateUtc (string, optional): End time boundary in ISO 8601 format.

    • signalId (string, optional): Optional signal ID.

    • timeoutSeconds (integer, optional, default: 30): Query timeout in seconds.

    • workspace (string, optional): Workspace identifier.

  • Example prompts for AI:

    • "Run a query in Seq to count errors grouped by HTTP status code"

    • "Find the top 10 slowest requests in Seq from the stream"


3. seq_list_signals

List all saved signals (predefined filters and searches) available in Seq.

  • Parameters:

    • sharedOnly (boolean, optional, default: true): List only shared signals.

    • workspace (string, optional): Workspace identifier.


4. seq_get_signal

Get full configuration, column definitions, and filter expressions of a specific signal.

  • Parameters:

    • signalId (string, required): The signal ID (e.g., signal-123).

    • workspace (string, optional): Workspace identifier.


5. seq_convert_filter

Convert relaxed/fuzzy user search syntax (e.g., free text or shorthand comparisons) into strict Seq filter expressions.

  • Parameters:

    • fuzzyFilter (string, required): The loose or natural search string (e.g., error, status:500, user==alice).

    • workspace (string, optional): Workspace identifier.


6. seq_tail_events

Wait for and capture recent or live stream events within a timeout window.

  • Parameters:

    • filter (string, optional): Filter expression applied to incoming events.

    • count (integer, optional, default: 10, max: 100): Maximum events to capture.

    • timeoutSeconds (integer, optional, default: 5, max: 30): Wait window in seconds.

    • workspace (string, optional): Workspace identifier.


๐Ÿ“ฆ Programmatic Library Usage

You can also use this package as a standalone library in your own Node.js / TypeScript applications:

import { SeqClient, createSeqMcpServer } from "@abhishekkumar00019/seq-mcp";

// 1. Using the SeqClient directly
const client = new SeqClient({
  serverUrl: "http://localhost:5341",
  apiKey: "your-api-key"
});

// Search events
const events = await client.searchEvents({
  filter: "@Level = 'Error'",
  count: 50,
  fromDateUtc: "2026-10-01T00:00:00Z"
});

// Run SQL query
const queryResult = await client.executeQuery({
  query: "select count(*) from stream group by time(1m)"
});

// 2. Creating an in-process MCP Server
const { server } = createSeqMcpServer({ client });

๐Ÿ“Š Dumping Dummy Test Data to Seq

You can dump a rich set of realistic dummy test logs (covering multiple microservices, all standard log levels from Verbose to Fatal, HTTP requests, DB deadlocks, timeouts, stack traces, and date ranges) directly into Seq:

# Provide API key via command-line option:
npm run dump-testdata -- --api-key YOUR_SEQ_API_KEY

# Or set SEQ_API_KEY and run:
SEQ_API_KEY=YOUR_SEQ_API_KEY npm run dump-testdata

# Custom event count and lookback window:
npm run dump-testdata -- -k YOUR_KEY -n 250 -d 7

If no API key is specified in arguments or environment, the script will interactively prompt for it in the terminal.


๐Ÿงช Development & Testing

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

# Install dependencies
npm install

# Run unit and integration tests
npm test

# Build for distribution
npm run build

๐Ÿ“„ License

MIT ยฉ Abhishek Kumar

Available Tools

6 tools
seq_convert_filterC

Convert a fuzzy or relaxed user search string into strict Seq filter syntax (e.g. converts 'error' or 'user==alice' into strict expressions).

ParametersJSON Schema
NameRequiredDescriptionDefault
workspaceNoOptional workspace identifier.
fuzzyFilterYesThe relaxed or fuzzy filter expression to convert.

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It does not say whether the tool errors on already-strict input, whether conversion is idempotent, whether the workspace parameter scopes or authorizes the call, or what the response contains (e.g. the converted string). For a transformation tool with zero annotation coverage, this is a notable gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with an embedded parenthetical example. It is efficient with no wasted words, though the example could have been separated for readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The purpose and input format are adequately conveyed, but with no annotations and no output schema, the description leaves the return value, error behavior, and workspace semantics unstated. Minimum viable for a simple two-parameter conversion tool, but not complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already documented in the schema, establishing a baseline of 3. The description adds a little meaning by showing example fuzzy inputs, but does not explain the optional workspace parameter or output semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (convert) and resource (fuzzy/relaxed user search string) with the target format (strict Seq filter syntax) and gives two concrete input examples. It is clear but does not differentiate itself from siblings like seq_search or seq_query, which may also accept filters.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit guidance on when to use this tool versus seq_search or seq_query, nor any mention of prerequisites or when conversion is unnecessary. The examples hint at the input shape, but no alternatives or exclusions are named.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

seq_get_signalC

Get detailed configuration and filter rules of a specific signal by ID.

ParametersJSON Schema
NameRequiredDescriptionDefault
signalIdYesThe ID of the signal to inspect (e.g., 'signal-123').
workspaceNoOptional workspace identifier.

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. 'Get' implies a read, but the definition never confirms it is non-mutating, says nothing about permissions, workspace scoping behavior when the optional field is omitted, or what happens for an unknown ID.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single well-formed sentence with the resource front-loaded and no filler. Efficient, though it is the only content and thus leaves no room for guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter read tool with full schema coverage and no output schema, this is minimally adequate. It would benefit from stating the read-only nature and whether the workspace parameter filters or overrides context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already documented in the schema, and the description adds no format, default, or scoping detail beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Get') and resource ('detailed configuration and filter rules of a specific signal'), which clearly distinguishes it from the list/search siblings. It stops short of naming an alternative, but the purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance, no prerequisites (e.g., that a signalId must first come from seq_list_signals or seq_search), and no exclusions. The 'by ID' phrasing weakly implies you need an ID, but nothing routes the agent between this and its siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

seq_list_signalsB

List available signals (saved searches and predefined filters) in Seq. Returns signal IDs, titles, descriptions, and filter expressions.

ParametersJSON Schema
NameRequiredDescriptionDefault
workspaceNoOptional workspace identifier.
sharedOnlyNoWhether to list only shared signals (default: true).

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It does disclose the return shape (signal IDs, titles, descriptions, filter expressions), which is valuable given there is no output schema, but it says nothing about permissions, pagination, or how the default sharedOnly=true scoping affects results.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with zero padding. The action is front-loaded, the domain gloss follows immediately, and the return fields are listed last where they belong.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple, side-effect-free list tool, this is nearly sufficient: it defines the resource and enumerates the returned fields in lieu of an output schema. The gap is the absence of any guidance on the workspace parameter's effect or on when this is the right entry point versus its siblings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters (workspace, sharedOnly) are already documented in the schema, including the default. The description adds no parameter-specific meaning beyond that, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('List') and resource ('signals') and even defines the domain term as 'saved searches and predefined filters', which is genuinely clarifying. It does not explicitly differentiate itself from the singular sibling seq_get_signal or from seq_search/seq_query, so it falls short of the 5 bar.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no when-to-use guidance, no prerequisites, and never names an alternative. An agent must infer that this is the discovery step before calling seq_get_signal, and nothing tells it when to prefer seq_search or seq_query instead.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

seq_queryC

Execute an analytical SQL-like query against Seq log data (e.g., "select count(*) from stream group by time(5m)", "select @Timestamp, @Message, @Level from stream where @Level = 'Error' limit 50").

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesSeq SQL query to execute.
signalIdNoOptional signal ID to scope query.
toDateUtcNoOptional end time boundary in ISO 8601 format.
workspaceNoOptional workspace identifier.
fromDateUtcNoOptional start time boundary in ISO 8601 format.
timeoutSecondsNoTimeout in seconds for the query.

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It implies a read/analytic operation but does not disclose whether it mutates state, permission requirements, rate limits, result-set limits, or how large-volume queries behave.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with the verb and resource first, followed by two illustrative examples. It is slightly long, and the second example is arguably redundant, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema and no annotations, so the description should carry more: it says nothing about the shape of results, result-size limits, or the read-only nature. For an analytical query tool with six parameters, this leaves gaps an agent would want filled.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all six parameters, setting the baseline at 3. The description's example queries add some syntax flavor for the 'query' param but clarify nothing about signalId, workspace, time bounds, or timeout.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Execute') and resource ('analytical SQL-like query against Seq log data') and gives concrete query examples. However, it never distinguishes from the sibling seq_search, which also operates on log data, so an agent cannot tell them apart without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description offers example queries but no guidance on when to choose this tool over seq_search or seq_tail_events, nor any prerequisites. The examples illustrate query syntax rather than usage conditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

seq_tail_eventsB

Wait for and capture recent or live stream events from Seq within a specified timeout window.

ParametersJSON Schema
NameRequiredDescriptionDefault
countNoMaximum number of events to capture (1-100, default: 10).
filterNoOptional Seq filter expression to apply to the stream.
workspaceNoOptional workspace identifier.
timeoutSecondsNoTime window in seconds to wait for events (1-30, default: 5).

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. It hints at blocking behavior ('Wait for') and a timeout window, but the timeout is already covered by the schema; it omits permission requirements, side effects, idempotency, and whether it blocks until the timeout or returns as soon as count is reached.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence that states the core action and scope without any filler. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given full schema coverage and no output schema, the description is adequate for basic invocation but lacks usage alternatives and behavioral context (e.g., blocking nature, return completeness). It leaves the agent with gaps when choosing between this and sibling search/query tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds no parameter-level meaning beyond what the schema provides, making 3 the appropriate baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb phrase ('Wait for and capture'), resource ('recent or live stream events from Seq'), and scope ('within a specified timeout window'). However, it does not explicitly differentiate itself from siblings such as seq_search or seq_query beyond the implied contrast of live/recent versus historical.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'Wait for and capture recent or live stream events' implies the tool is used when live or recent event monitoring is needed, but no explicit when-to-use, when-not-to-use, or named alternatives are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 6 tool updatesv1.0.1
    • First observedseq_convert_filter
    • First observedseq_get_signal
    • First observedseq_list_signals
    • First observedseq_query
    • First observedseq_search
    • First observedseq_tail_events

TDQS

B3.4/5.0

Scored across 6 tools

Disambiguation4/5

Most tools are clearly distinct: signals listing/retrieval, filter conversion, and live tailing each have unique purposes. However, seq_search for historical events and seq_query for analytical SQL-like queries could be confused by an agent deciding how to retrieve or analyze log data. Descriptions provide enough guidance to resolve most ambiguity.

Naming Consistency5/5

All tools use a consistent seq_ prefix followed by a verb_noun pattern in snake_case (seq_search, seq_list_signals, seq_get_signal, etc.). No mixed conventions or vague naming.

Tool Count5/5

Six tools is well-scoped for a Seq log querying server, covering search, analytical query, signal inspection, filter conversion, and live tailing without bloat. Each tool earns its place for the core workflows.

Completeness4/5

The server covers key read and query operations: historical search, SQL-like analytics, signal discovery, filter conversion, and live tailing. Minor gaps exist around managing signals (e.g., create/update/delete) and exporting results, but core agent workflows are supported.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    B
    quality
    D
    maintenance
    Enables LLMs to query and analyze logs from SEQ structured logging server with capabilities for searching events, retrieving event details, analyzing log patterns, and accessing saved searches.
    5
    MIT
  • A
    license
    D
    quality
    A
    maintenance
    Integrates AI assistants with Graylog to query and analyze log data using Elasticsearch syntax and stream-specific filtering. It enables users to perform advanced searches, retrieve log statistics, and manage Graylog streams through natural language.
    9
    12
    MIT
  • A
    license
    D
    quality
    B
    maintenance
    A Model Context Protocol server that provides AI agents with controlled read access to Datalust Seq instances for log analysis and monitoring. It enables agents to search events, execute data queries, and retrieve information about signals, dashboards, and alerts.
    100
    3
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    Connects AI assistants to cloud and SaaS logs via Tailpipe, enabling natural language querying and analysis of log data.
    9 npm
    7
    Apache 2.0