@loguro/mcp

MCP server for querying Loguro logs directly from Claude Code.

Auth

The MCP server uses a Loguro PAT (personal access token). Two ways to provide it:

A) Reuse the token saved by the CLI (zero config):

loguro login    # saves to ~/.config/loguro/auth.json

The MCP server picks it up automatically.

B) Explicit env var (Claude config / CI):

LOGURO_TOKEN=pat_…

Config

| Var | Required | Description | |-----|----------|-------------| | LOGURO_TOKEN | ✅ unless auth.json exists | Your Loguro PAT (pat_…) | | LOGURO_PROJECT | optional | Default project slug (skip passing it each call) | | LOGURO_BASE_URL | optional | Override base URL (default: https://logu.ro) |

Claude Code setup

Add to ~/.claude/settings.json (global) or .claude/settings.json (per project):

With saved CLI auth (recommended):

{
  "mcpServers": {
    "loguro": {
      "command": "bunx",
      "args": ["@loguro/mcp"],
      "env": {
        "LOGURO_PROJECT": "your-project-slug"
      }
    }
  }
}

With explicit token:

{
  "mcpServers": {
    "loguro": {
      "command": "bunx",
      "args": ["@loguro/mcp"],
      "env": {
        "LOGURO_TOKEN": "pat_…",
        "LOGURO_PROJECT": "your-project-slug"
      }
    }
  }
}

Tools

| Tool | Description | |------|-------------| | query_logs | Query logs with any filter: level, message, search, date range (incl. notFrom/notTo), trace, slow, rich context filters with operators (>=, !=, etc.) and negation, memory mode, cursor or offset pagination | | get_log_timeline | Get logs around a specific log ID — context window for an error | | get_distinct_values | List unique values for a field (e.g. all levels, all envs) | | group_logs | Group logs by a field with explicit groupValues | | get_slow_logs | Shortcut for slow requests above N ms | | sample_logs | Random sample — useful for exploring an unfamiliar project |

When to use the MCP vs CLI vs Web Console

The MCP server is one of three ways to interact with Loguro. Each fits a different moment in the workflow.

| Reach for MCP (this) when... | Reach for CLI when... | Reach for Web Console when... | |---|---|---| | Debugging in the IDE: ask Claude/Cursor about a failure and let it query logs iteratively | Reproducible scripts: cron jobs, CI alerts, loguro logs --json \| jq | Visual exploration: charts, timeline view, replay, saved view dashboards | | Natural-language questions: "show me errors after the deploy at 14:00" | Direct queries you already know: loguro logs -l error --from 1h | Setting up integrations interactively (OAuth flows, Slack app install) | | Multi-step investigation where Claude calls get_log_timeline then group_logs then get_distinct_values autonomously | One-shot ad-hoc queries from terminal, piping into other tools | First-time onboarding for someone new to your project | | Sharing context with the AI without copy-pasting log dumps | Bulk operations: project + key + alert in one shell session | Issue creation with rich UI, log shares, embed widgets |

Token footprint

This MCP exposes 6 focused tools (query_logs, get_log_timeline, get_distinct_values, group_logs, get_slow_logs, sample_logs) — ~1k tokens of system prompt vs the 5–10k tokens of MCPs that ship 30+ generic tools. That overhead matters when you run smaller models or have a long debugging conversation.

Zero-config setup

If you've already run loguro login, this MCP picks up the saved PAT from ~/.config/loguro/auth.json automatically. No second login, no per-session credentials. The same token works across all your projects.

For CI or shared agents where the CLI isn't installed, set LOGURO_TOKEN in env (see Config above).

Latency

The MCP makes a single fetch per tool call (no SQL round-tripping through an interpreter). For interactive AI workflows this is fast enough that Claude can chain 3–5 tool calls in a single turn without lag.

For bulk fetches (10k+ rows, exports, scripted pipelines), the CLI streams JSON faster — use loguro logs --json | jq instead.

Combine them

• CLI for setup and scripted workflows
• MCP for IDE-driven debugging and natural-language exploration
• Web for visual analysis and saved-view dashboards

All three share auth and read the same data — switch freely based on what's least friction in the moment.

Context filters

context is an array of filter objects:

[
  { "key": "user_id", "value": "42" },
  { "key": "duration", "value": 500, "op": ">=" },
  { "key": "env", "value": "staging", "negate": true }
]

Operators: = (default), !=, >, <, >=, <=. negate: true excludes (maps to notContext_<key>).