logscale-mcp-server

LogScale MCP Server Query CrowdStrike LogScale logs from AI assistants via the Model Context Protocol

Features • Quick Start • Tools • Usage • Queries • Security • CI • Architecture • Contributing

Introduction

LogScale MCP Server lets you query CrowdStrike LogScale logs through natural language in VS Code Copilot Chat, Claude Desktop, or any MCP-compatible client. Instead of writing raw CQL queries and managing API calls, just ask:

"Show me errors in the xxxx namespace from the last hour"

"Find all 500 errors from the xyxyxy pod today"

"Search logs for request ID f6796646b043d231bf67f589b7306e9b"

The server handles query submission, polling, result formatting, and pagination automatically.

Features

• 2 MCP tools — search_logs and get_query_job for comprehensive log querying
• CrowdStrike Query Language (CQL) — full support for filters, pipes, aggregations, and field searches
• Automatic poll loop — submits query jobs and polls with server-suggested intervals until completion
• Smart result formatting — structured output with field statistics, event counts, and metadata
• Configurable defaults — custom timeouts, pagination limits, poll intervals, and max events
• Time range support — relative (1h, 7d) and absolute (epoch milliseconds) time ranges
• VS Code Extension — bundled extension with built-in configuration UI for LogScale connection settings
• Monorepo architecture — clean separation between server (logscale-mcp-server) and extension (logscale-mcp-vscode)

Quality & Security

Quick Start

Prerequisites

• Node.js ≥ 18
• pnpm (recommended) or npm
• A LogScale instance with API access and a Bearer token

Install from npm

# Install globally
npm install -g logscale-mcp-server

# Or run directly with npx
npx logscale-mcp-server

Install from Source

git clone https://github.com/your-org/logscale-mcp-server.git
cd logscale-mcp-server
pnpm install
pnpm -r build

Configuration

Tools

search_logs

Submit a CQL query, wait for results, and return formatted log events.

get_query_job

Check status or retrieve results of an existing query job.

Usage

VS Code (MCP)

Add to .vscode/mcp.json:

{
  "servers": {
    "logscale": {
      "command": "npx",
      "args": ["-y", "logscale-mcp-server"],
      "env": {
        "LOGSCALE_BASE_URL": "https://your-logscale-instance.com",
        "LOGSCALE_API_TOKEN": "your-api-token",
        "LOGSCALE_REPOSITORY": "your-repository"
      }
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "logscale": {
      "command": "npx",
      "args": ["-y", "logscale-mcp-server"],
      "env": {
        "LOGSCALE_BASE_URL": "https://your-logscale-instance.com",
        "LOGSCALE_API_TOKEN": "your-api-token",
        "LOGSCALE_REPOSITORY": "your-repository"
      }
    }
  }
}

VS Code Extension

Install the bundled VS Code extension for a GUI-configured experience or download from marketplace:

# From VSCode Extensions marketplace
Search "LogScale MCP Server", install.

# From local VSIX
code --install-extension packages/vscode-extension/logscale-mcp-vscode-0.1.0.vsix

The extension provides VS Code settings for logscale.baseUrl, logscale.repository, logscale.timeoutMs, logscale.pollIntervalMs, and logscale.maxEvents.

Development

pnpm run dev                # Start server in dev mode
pnpm -r build               # Build all packages
pnpm run test:coverage      # Run tests with coverage
pnpm run ci                 # Full CI pipeline locally

Test with MCP Inspector

npx @modelcontextprotocol/inspector node packages/server/dist/index.js

CQL Query Examples

# Simple namespace filter
"kubernetes.namespace_name" = "your-namespace"

# Filter by namespace AND app label
"kubernetes.namespace_name" = "your-namespace"
| "kubernetes.labels.app_kubernetes_io/instance" = "your-instance-name"

# Search for errors in a namespace
kubernetes.namespace_name = "your-namespace" | ERROR

# Search by correlation ID
kubernetes.namespace_name = "your-namespace" | "f6796646b043d231bf67f589b7306e9b"

# Chain multiple filters
kubernetes.namespace_name = "your-namespace"
| 81bd572b6f202eccb9538408cb764c89
| "Pod Network CIDR is not provided"

# Aggregations
ERROR | groupBy(kubernetes.pod_name, function=count())
ERROR | top(log, limit=10)
ERROR | timechart(span=5m)

Time Ranges

Architecture

AI Client (VS Code Copilot, Claude Desktop)
    ↕  MCP (stdio transport)
LogScale MCP Server (TypeScript / Node.js)
    ↕  HTTPS (REST API)
CrowdStrike LogScale (Query Jobs API)

The server uses LogScale's 2-step Query Jobs API:

1. Submit — POST /api/v1/repositories/{repo}/queryjobs → returns job ID
2. Poll — GET /api/v1/repositories/{repo}/queryjobs/{id} → poll until done, return results

Security

CI Pipeline

The CI runs 11 jobs on every push and pull request:

┌─────────────┐  ┌───────────────────────┐  ┌──────────────────┐
│  typecheck   │  │  lint (ESLint+security)│  │  format (Prettier)│
└──────┬───────┘  └───────────┬────────────┘  └────────┬─────────┘
       │                      │                        │
       ▼                      ▼                        ▼
┌──────────────────────────────────────────────────────────────────┐
│              test (Node 18 / 20 / 22 + coverage)                │
└──────────────────────────────┬───────────────────────────────────┘
                               ▼
                    ┌──────────────────┐
                    │      build       │
                    └────────┬─────────┘
                             ▼
                 ┌───────────────────────┐
                 │  package-extension    │
                 │  (VSIX artifact)      │
                 └───────────────────────┘

     (parallel)
┌──────────────────┐  ┌──────────┐  ┌────────────────────┐  ┌──────────┐
│  security-audit  │  │  codeql  │  │ dependency-review  │  │ gitleaks │
│  (pnpm audit)    │  │          │  │   (PR only)        │  │          │
└──────────────────┘  └──────────┘  └────────────────────┘  └──────────┘
                               │
                               ▼
                    ┌──────────────────┐
                    │   sbom (Trivy)   │
                    └──────────────────┘

Troubleshooting

"Unexpected token '<'" / HTML response error

The LOGSCALE_BASE_URL is likely incorrect. Many LogScale deployments serve the API under a path prefix (e.g., /logs). Check the URL in your browser's network tab — if API calls go to https://host/logs/api/v1/..., set:

LOGSCALE_BASE_URL=https://your-host/logs

Authentication failures (401/403)

Verify your LOGSCALE_API_TOKEN is valid and has read permission on the target repository.

Repository not found (404)

Check the LOGSCALE_REPOSITORY name matches exactly (case-sensitive).

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feat/my-feature
3. Make changes following Conventional Commits
4. Run the full CI locally: pnpm run ci
5. Submit a pull request

Commit Format

feat: add new search filter       → minor version bump
fix: handle empty results          → patch version bump
feat!: redesign query API          → major version bump

License

MIT