# logflare-mcp

MCP server for the [Logflare](https://logflare.app) Management API. Exposes sources,
endpoints, and ad-hoc SQL query tools to MCP clients (Claude Code, Claude Desktop, Cursor,
…) over stdio.

Built on the official `@modelcontextprotocol/sdk` and talks directly to the public
Logflare REST API — no third-party auth proxy.

## Tools

| Tool | Description |
|------|-------------|
| `list_sources` | List all sources available to the API key |
| `get_source` | Fetch a single source by token |
| `get_source_schema` | Inferred field types for a source |
| `get_recent_events` | Most recent events from a source |
| `list_endpoints` | Saved query endpoints |
| `query_endpoint` | Run a saved endpoint by UUID or name, with parameters |
| `execute_query` | Run ad-hoc BigQuery / Postgres / ClickHouse SQL |

## Install

```bash
git clone git@github.com:fasterv410/logflare-mcp.git
cd logflare-mcp
pnpm install
pnpm build
```

## Configure

Get your Logflare API key from <https://logflare.app/access-tokens>.

```bash
cp .env.example .env
# edit .env and paste your key
```

| Variable | Required | Default | Notes |
|----------|----------|---------|-------|
| `LOGFLARE_API_KEY` | yes | — | Access token |
| `LOGFLARE_BASE_URL` | no | `https://logflare.app` | For self-hosted Logflare |
| `LOGFLARE_AUTH_STYLE` | no | `bearer` | Use `x-api-key` for legacy keys |
| `LOGFLARE_DEFAULT_SOURCE_TOKEN` | no | — | Default source when the tool arg is omitted |

## Register with Claude Code

```bash
claude mcp add logflare -- node /absolute/path/to/logflare-mcp/dist/index.js
```

Or add manually to `~/.claude.json`:

```json
{
  "mcpServers": {
    "logflare": {
      "command": "node",
      "args": ["/absolute/path/to/logflare-mcp/dist/index.js"],
      "env": {
        "LOGFLARE_API_KEY": "lf-xxxxxxxx",
        "LOGFLARE_DEFAULT_SOURCE_TOKEN": "optional-uuid"
      }
    }
  }
}
```

## Register with Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "logflare": {
      "command": "node",
      "args": ["/absolute/path/to/logflare-mcp/dist/index.js"],
      "env": { "LOGFLARE_API_KEY": "lf-xxxxxxxx" }
    }
  }
}
```

## Dev

```bash
pnpm dev         # tsx watch mode
pnpm build       # emit dist/
pnpm typecheck
```

Smoke test from the shell:

```bash
LOGFLARE_API_KEY=xxx printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | node dist/index.js
```

## Notes

- Auth defaults to `Authorization: Bearer <key>` (per Logflare's OpenAPI spec). Set
  `LOGFLARE_AUTH_STYLE=x-api-key` to fall back to the legacy `X-API-KEY` header.
- `execute_query` accepts exactly one of `bq_sql`, `pg_sql`, `ch_sql`.
- Prefer `query_endpoint` with saved endpoints over `execute_query`; saved endpoints
  give you parameter validation and caching on Logflare's side.

## License

MIT