# kairosdb-mcp-server

MCP server for querying KairosDB (REST API v1) from Claude Desktop.

## Available tools

| Tool | Description |
|-------|-------------|
| `kairosdb_query_range` | Raw or aggregated data over a relative range (e.g. last 24h) |
| `kairosdb_query_absolute` | Data over an absolute range (ISO 8601 dates) |
| `kairosdb_last_value` | Latest known value of a metric |
| `kairosdb_aggregate` | Several aggregations (min/max/avg) in a single request |
| `kairosdb_list_metrics` | Lists all available metrics |
| `kairosdb_list_tag_values` | Available values for a given tag |
| `kairosdb_health` | Checks the server status |

## Installation

```bash
cd kairosdb-mcp-server
npm install
npm run build
```

Verify the build is OK:
```bash
node dist/index.js
# Should print: [kairosdb-mcp] Starting. KairosDB URL: http://localhost:8080
# Then: [kairosdb-mcp] Ready.
# Then wait for MCP messages (stdio)
```

## Claude Desktop configuration

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "directus": {
      // ... your existing Directus config
    },
    "kairosdb": {
      "command": "node",
      "args": ["/absolute/path/to/kairosdb-mcp-server/dist/index.js"],
      "env": {
        "KAIROSDB_URL": "http://your-kairosdb-server:8080",
        "KAIROSDB_USER": "",
        "KAIROSDB_PASSWORD": ""
      }
    }
  }
}
```

> Replace `/absolute/path/to/` with the actual path on your machine.
> Leave `KAIROSDB_USER` and `KAIROSDB_PASSWORD` empty if authentication isn't used.

## Environment variables

| Variable | Default | Description |
|----------|--------|-------------|
| `KAIROSDB_URL` | `http://localhost:8080` | KairosDB server URL |
| `KAIROSDB_USER` | _(empty)_ | HTTP Basic username (optional) |
| `KAIROSDB_PASSWORD` | _(empty)_ | HTTP Basic password (optional) |

## Example questions in Claude Desktop

### Exploration
- "List all KairosDB metrics"
- "What values exist for the tag 'host'?"
- "Is KairosDB available?"

### Real-time data
- "What is the latest value of the metric `server.cpu_usage` for tag host=web-01?"

### Time series
- "Give me the data for `network.latency` over the last 48 hours"
- "Show me the memory usage between 2024-01-01 and 2024-01-31"

### Aggregations
- "Compute the min/max/avg of `http.request_duration` hourly over the last 7 days for server web-01"

### Combined with Directus
- "Show me all hosts in the 'Payment Service' group, then give me their latest CPU value in KairosDB"

## Architecture

```
src/
├── index.ts              # Entry point, stdio transport
├── constants.ts          # URL, limits
├── types.ts              # KairosDB API interfaces
├── schemas/
│   └── index.ts          # Zod schemas for all tools
├── services/
│   ├── kairosdb-client.ts  # KairosDB HTTP client
│   └── formatters.ts       # Markdown/JSON formatting
└── tools/
    ├── query-tools.ts      # query_range, query_absolute, last_value
    └── aggregate-tools.ts  # aggregate, list_metrics, list_tag_values, health
```