Provides containerized deployment options for the SEQ MCP server, supporting various environment configurations and networking setups for connecting to SEQ instances.
Supports configuration through .env files for setting SEQ server connection details and authentication credentials.
Offers integration with GitHub Container Registry for pulling pre-built Docker images of the SEQ MCP server.
Provides automated CI/CD pipeline for building, testing, and publishing SEQ MCP server images to container registries.
Allows running the SEQ MCP server directly with Node.js, supporting configuration through environment variables or .env files.
SEQ MCP Server
An MCP (Model Context Protocol) server that enables LLMs to query and analyze logs from SEQ structured logging server.
Features
Search Events: Query logs with powerful SEQ filter syntax
Get Event Details: Retrieve complete information about specific log events
Analyze Logs: Statistical analysis of log patterns over time periods
List Signals: Access saved searches/signals configured in SEQ
Health Check: Monitor SEQ server status
Prerequisites
Node.js 18+
Access to a SEQ server instance
SEQ API key (optional but recommended for secure instances)
Installation
Option 1: Using Docker (Recommended)
Option 2: From Source
Configuration
Environment Variables
Variable | Description | Default | Required |
| URL of your SEQ server |
| Yes |
| API key for authentication | - | No* |
| Default number of events to return |
| No |
| Request timeout in milliseconds |
| No |
*Required if your SEQ instance has authentication enabled
Setup Instructions
Copy the example environment file:
Edit
.env
with your SEQ server details:
Usage with Claude Desktop
macOS
Open Claude Desktop settings
Navigate to "Developer" → "Edit Config"
Add the SEQ server configuration:
Windows
Open Claude Desktop settings
Navigate to "Developer" → "Edit Config"
Add the SEQ server configuration:
Usage with Claude Code
Option 1: Using .env file
Create a
.env
file in your project root:
Add to your Claude Code MCP configuration:
Option 2: Using environment variables directly
Option 3: Using system environment variables
Set environment variables in your shell:
Then use a simple configuration:
Getting API Keys from SEQ
Open your SEQ instance in a web browser
Navigate to Settings → API Keys
Click "Add API Key"
Provide a title (e.g., "MCP Server")
Set appropriate permissions (typically "Read" is sufficient)
Copy the generated API key
Example Usage in Claude
Once configured, you can query your logs naturally:
Available Tools
search_events
Search for events with filters:
get_event
Get detailed information about a specific event by ID.
analyze_logs
Analyze log patterns:
list_signals
List all configured signals (saved searches) in SEQ.
check_health
Check SEQ server health status.
Troubleshooting
Connection Issues
Verify SEQ is running:
curl http://localhost:5341/api/healthCheck API key permissions: Ensure your API key has "Read" permissions
Network/Firewall: Ensure the MCP server can reach your SEQ instance
Timeout errors: Increase
SEQ_TIMEOUT
for large queries
Common Errors
"Unauthorized": Check your API key is correct
"Connection refused": Verify SEQ_URL and that SEQ is running
"Timeout": Query may be too complex, try adding more specific filters
Development
SEQ Query Examples
Level = 'Error'
- All error logs@Message like '%timeout%'
- Messages containing "timeout"Application = 'MyApp' and Level in ['Warning', 'Error']
- Warnings and errors from MyApp@Timestamp > Now() - 1h
- Events from last hourStatusCode >= 400
- HTTP errorsEnvironment = 'Production' and ResponseTime > 1000
- Slow production requestsUserId = '12345'
- All logs for specific user@Exception is not null
- All logs with exceptions
Advanced Configuration
Using with Docker
If SEQ is running in Docker:
Using with Remote SEQ
For cloud-hosted SEQ instances:
Docker Usage
Running the Container
Using with Claude Desktop (Docker)
Add to your Claude Desktop configuration:
Using with Claude Code (Docker)
Docker Compose Example
Create a docker-compose.yml
:
Architecture
MCP Server: Handles tool definitions and request routing
SEQ Client: Manages API communication with SEQ
Type Safety: Full TypeScript with Zod validation
Error Handling: Graceful degradation and meaningful error messages
Security
API keys are never logged or exposed
All requests are validated before execution
Timeout protection for long-running queries
Read-only operations (no log modification)
Supports both HTTP and HTTPS connections
CI/CD Pipeline
This project uses GitHub Actions for continuous integration and deployment:
CI: Runs on every push and PR to ensure code quality
Linting with ESLint
Type checking with TypeScript
Unit tests with Vitest
Multi-version Node.js testing (18.x, 20.x)
Docker Publishing:
Automatically builds and publishes to GitHub Container Registry on main branch
Publishes to Docker Hub on version tags
Multi-platform builds (linux/amd64, linux/arm64)
Semantic versioning tags
Creating a Release
Tag your release:
git tag v1.0.0 git push origin v1.0.0The GitHub Action will automatically:
Build multi-platform Docker images
Push to
ghcr.io/roeej/seq-mcp:1.0.0
Push to
dockerhub/roeej/seq-mcp:1.0.0
(requires secrets setup)
Required GitHub Secrets
For Docker Hub publishing (optional):
DOCKERHUB_USERNAME
: Your Docker Hub usernameDOCKERHUB_TOKEN
: Docker Hub access token
Note: GitHub Container Registry (ghcr.io) publishing works automatically with the repository's GITHUB_TOKEN, no additional setup required.
Contributing
Fork the repository
Create your feature branch (
git checkout -b feature/amazing-feature
)Commit your changes (
git commit -m 'Add some amazing feature'
)Push to the branch (
git push origin feature/amazing-feature
)Open a Pull Request
License
MIT
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
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.
- Features
- Prerequisites
- Installation
- Configuration
- Usage with Claude Desktop
- Usage with Claude Code
- Getting API Keys from SEQ
- Example Usage in Claude
- Available Tools
- Troubleshooting
- Development
- SEQ Query Examples
- Advanced Configuration
- Docker Usage
- Architecture
- Security
- CI/CD Pipeline
- Contributing
- License
Related Resources
Related MCP Servers
- AsecurityFlicenseAqualityInteracts with LogSeq via its API.Last updated -117
- -securityFlicense-qualityIntegrates with Sumo Logic's API to enable log search with configurable queries and time ranges, supporting error handling and easy deployment via Docker.Last updated -05
- AsecurityAlicenseAqualityA server that enables LLMs to programmatically interact with Logseq knowledge graphs, allowing creation and management of pages and blocks.Last updated -1024MIT License
- -securityFlicense-qualityEnables querying log data stored in SQLite databases through the Model Context Protocol, allowing natural language interactions with log analysis.Last updated -