# Hybrid Recursive Ladder

> Hybrid Recursive Ladder is an open-source MCP server for analytics and data. Query planner that fetches long time-series ranges in a handful of requests. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted
- **Website:** https://magicsquarekey.github.io/hybrid_recursive_ladder_algorithm/
- **Repository:** https://github.com/magicsquarekey/hybrid_recursive_ladder_algorithm
- **MCP Registry name:** io.github.MagicSquarekey/hybrid-recursive-ladder
- **Categories:** analytics and data
- **Listing updated:** 2026-11-15

## About

The idea is a calendar ladder: instead of asking a source for one value per output bucket, the planner splits a date range into complete months, days, hours and minutes, fetches each run of the same level once at the next finer aggregation, and sums the results locally. The author's example is a ThingsBoard query that took 139 seconds for 1,140 buckets because each bucket needed up to four HTTP calls.

The site's worked example covers 2026-01-01 to 2026-10-21, which breaks into 97 segments and roughly 5 to 7 requests, avoiding 423,049 minute buckets. Reported timings on a production deployment over a VPN include about 4 requests and 0.64 s for two days at minute level, and 1.18 s cold or 0.20 s warm for a year at day level. Latency depends on the network, source load and data density.

The MCP package (PyPI `hybrid-recursive-ladder-mcp`, stdio) picks its backend with HL_SOURCE: a built-in demo (default), ThingsBoard, or a PostgreSQL local materialized store. Other settings cover the ThingsBoard URL and credentials, the timezone for calendar boundaries and the finest level (minute, hour, day or month). It is released under the MIT licence, and the author states it is a query-planning composition, not a new database.

## Features

- **Calendar decomposition:** Splits a range into complete calendar units and pushes partial edges to finer levels.
- **One fetch per level:** Fetches each contiguous run at its next finer aggregation, then folds locally.
- **Selectable backends:** Demo, ThingsBoard or PostgreSQL via HL_SOURCE.
- **Coverage-aware gaps:** Can fetch only sub-ranges not already covered locally.
- **Configurable finest level:** Set minute, hour, day or month with HL_FINEST.
- **Offline demo:** The demo mode needs no database, network or configuration.

## Good for

- Cut dashboard query time on bucket-limited time-series APIs
- Aggregate months of ThingsBoard telemetry through an AI client
- Plan how many requests a long-range report will need
- Benchmark request counts without running a server

## Install

### Claude Code (Terminal)

```sh
claude mcp add hybrid-recursive-ladder --env HL_TB_PASSWORD='<HL_TB_PASSWORD>' --env HL_TB_TOKEN='<HL_TB_TOKEN>' --env HL_PG_DSN='<HL_PG_DSN>' -- uvx hybrid-recursive-ladder-mcp
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "hybrid-recursive-ladder": {
      "command": "uvx",
      "args": [
        "hybrid-recursive-ladder-mcp"
      ],
      "env": {
        "HL_TB_PASSWORD": "<HL_TB_PASSWORD>",
        "HL_TB_TOKEN": "<HL_TB_TOKEN>",
        "HL_PG_DSN": "<HL_PG_DSN>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "hybrid-recursive-ladder": {
      "command": "uvx",
      "args": [
        "hybrid-recursive-ladder-mcp"
      ],
      "env": {
        "HL_TB_PASSWORD": "<HL_TB_PASSWORD>",
        "HL_TB_TOKEN": "<HL_TB_TOKEN>",
        "HL_PG_DSN": "<HL_PG_DSN>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "hybrid-recursive-ladder": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "hybrid-recursive-ladder-mcp"
      ],
      "env": {
        "HL_TB_PASSWORD": "<HL_TB_PASSWORD>",
        "HL_TB_TOKEN": "<HL_TB_TOKEN>",
        "HL_PG_DSN": "<HL_PG_DSN>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "hybrid-recursive-ladder": {
      "command": "uvx",
      "args": [
        "hybrid-recursive-ladder-mcp"
      ],
      "env": {
        "HL_TB_PASSWORD": "<HL_TB_PASSWORD>",
        "HL_TB_TOKEN": "<HL_TB_TOKEN>",
        "HL_PG_DSN": "<HL_PG_DSN>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "hybrid-recursive-ladder": {
      "command": "uvx",
      "args": [
        "hybrid-recursive-ladder-mcp"
      ],
      "env": {
        "HL_TB_PASSWORD": "<HL_TB_PASSWORD>",
        "HL_TB_TOKEN": "<HL_TB_TOKEN>",
        "HL_PG_DSN": "<HL_PG_DSN>"
      }
    }
  }
}
```

## FAQ

### Which data sources does it support?

The registry entry lists a demo source, ThingsBoard and PostgreSQL.

### Do I need a database to try it?

No. The demo needs no database, network or configuration.

### Which timezone does it use?

HL_TIMEZONE sets it; the default is Asia/Shanghai.

### What licence is it under?

MIT.

### Is Hybrid Recursive Ladder free?

Yes. Hybrid Recursive Ladder is open source, so you can use and self-host it for free.

### How do I add Hybrid Recursive Ladder to Claude Code?

Run this command in your terminal: claude mcp add hybrid-recursive-ladder --env HL_TB_PASSWORD='<HL_TB_PASSWORD>' --env HL_TB_TOKEN='<HL_TB_TOKEN>' --env HL_PG_DSN='<HL_PG_DSN>' -- uvx hybrid-recursive-ladder-mcp

### What are the best alternatives to Hybrid Recursive Ladder?

The closest alternatives to Hybrid Recursive Ladder are Agent-Native Analytics, Google Ads + Meta Ads + SEO/GEO MCP, Tapetide - Indian Stock Market MCP, World Monitor and CompanyData.

## Alternatives

- [Agent-Native Analytics](https://ai-powered.com/mcp/agent-native-analytics): Agent-Native Analytics is an open-source MCP server for analytics and data.
- [Google Ads + Meta Ads + SEO/GEO MCP](https://ai-powered.com/mcp/google-ads-meta-ads-seo-geo-mcp): Google Ads + Meta Ads + SEO/GEO MCP is a freemium MCP server for marketing and seo.
- [Tapetide - Indian Stock Market MCP](https://ai-powered.com/mcp/tapetide-indian-stock-market-mcp): Tapetide - Indian Stock Market MCP is a freemium MCP server for finance and payments.
- [World Monitor](https://ai-powered.com/mcp/world-monitor): World Monitor is a freemium MCP server for analytics and data.
- [CompanyData](https://ai-powered.com/mcp/companydata): CompanyData is a paid MCP server for analytics and data.
- [ChartAnt](https://ai-powered.com/mcp/chartant): ChartAnt is a freemium MCP server for design and media.
- [Quantivex Research](https://ai-powered.com/mcp/quantivex-research): Quantivex Research is a free MCP server for finance and payments.
- [Provyan](https://ai-powered.com/mcp/provyan): Provyan is a free MCP server for finance and payments.

---
Source: https://ai-powered.com/mcp/hybrid-recursive-ladder
