# VictoriaLogs MCP Server

MCP (Model Context Protocol) server for querying VictoriaLogs using LogsQL.

## Installation

### Via npm (recommended)

```bash
npm install -g victorialogs-mcp-server
```

Or run directly with npx:

```bash
npx victorialogs-mcp-server
```

### From source

```bash
git clone https://github.com/user/victorialogs-mcp.git
cd victorialogs-mcp
npm install
npm run build
```

## Configuration

Set environment variables:

| Variable | Description | Default |
|----------|-------------|---------|
| `VICTORIALOGS_URL` | VictoriaLogs server URL | `http://localhost:9428` |
| `VICTORIALOGS_ACCOUNT_ID` | Tenant Account ID (optional) | - |
| `VICTORIALOGS_PROJECT_ID` | Tenant Project ID (optional) | - |

## Usage with Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "victorialogs": {
      "command": "npx",
      "args": ["victorialogs-mcp-server"],
      "env": {
        "VICTORIALOGS_URL": "http://localhost:9428"
      }
    }
  }
}
```

## Usage with Cursor

Add to `.cursor/mcp.json` in your project:

```json
{
  "mcpServers": {
    "victorialogs": {
      "command": "npx",
      "args": ["victorialogs-mcp-server"],
      "env": {
        "VICTORIALOGS_URL": "http://localhost:9428"
      }
    }
  }
}
```

## Available Tools

| Tool | Description |
|------|-------------|
| `victorialogs_query` | Execute LogsQL queries and get log entries |
| `victorialogs_hits` | Get hit count statistics over time |
| `victorialogs_facets` | Get most frequent values per field |
| `victorialogs_stats_query` | Execute stats query at a point in time |
| `victorialogs_stats_query_range` | Execute stats query over a time range |
| `victorialogs_streams` | Query log streams |
| `victorialogs_stream_ids` | Get stream IDs |
| `victorialogs_stream_field_names` | List stream field names |
| `victorialogs_stream_field_values` | Get stream field values |
| `victorialogs_field_names` | List all log field names |
| `victorialogs_field_values` | Get values for a specific field |
| `victorialogs_tenants` | List available tenants |

## Example Queries

```
# Find error logs
victorialogs_query(query="error")

# Filter by app and time
victorialogs_query(query='{app="nginx"} AND _time:1h')

# Get stats
victorialogs_stats_query(query="_time:1d | stats by (level) count(*)")

# Get hit counts over time
victorialogs_hits(query="error", start="24h", step="1h")

# Explore fields
victorialogs_field_names(query="*")
victorialogs_field_values(query="*", field="level")
```

## LogsQL Reference

See [VictoriaLogs LogsQL documentation](https://docs.victoriametrics.com/victorialogs/logsql/) for query syntax.

## License

MIT