Skip to content
MCP server

Hybrid Recursive Ladder

Query planner that fetches long time-series ranges in a handful of requests

Runs locallyStatus and history
Install
Pricing
Open source
Platforms
CLI, self-hosted
Runs
Locally
Version
0.0.8
Listing updated
2 days ago

About Hybrid Recursive Ladder

Hybrid Recursive Ladder is an open-source MCP server for analytics and data. It runs locally on your machine and is started by your AI client.

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.

Install

Run in a 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

Add to claude_desktop_config.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>"
      }
    }
  }
}

Add to ~/.cursor/mcp.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>"
      }
    }
  }
}

Add to .vscode/mcp.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>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.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>"
      }
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "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>"
      }
    }
  }
}

Configuration

  • HL_SOURCESource backend: demo (default), thingsboard, or postgres.
  • HL_TB_URLThingsBoard base URL, for example http://localhost:9090.
  • HL_TB_USERNAMEThingsBoard username; pair with HL_TB_PASSWORD.
  • HL_TB_PASSWORDThingsBoard password.
  • HL_TB_TOKENThingsBoard access token, used instead of username and password.
  • HL_PG_DSNPostgreSQL DSN for the local materialized store.
  • HL_TIMEZONEIANA timezone for calendar boundaries; default Asia/Shanghai.
  • HL_FINESTFinest ladder level: minute, hour, day, or month.

What it does

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

Pricing

Open source

MIT licence; free to run

Prices change. Check magicsquarekey.github.io before you buy.

Hybrid Recursive Ladder 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 to Hybrid Recursive Ladder

  1. Open-source analytics app where an AI agent builds charts and dashboards from your data

    • Remote
    • Open source
    • 7.7K GitHub stars
    • Analytics and data
  2. Hosted MCP connector for managing Google Ads, Meta Ads, GA4 and Search Console from chat

    • 8 tools
    • Remote
    • Freemium
    • 8.1K GitHub stars
    • Marketing and SEO
  3. Indian NSE and BSE stock market data for AI assistants through 48 MCP tools

    • 17 tools
    • Remote
    • Freemium
    • 150 GitHub stars
    • Finance and payments
  4. World Monitor

    MCP server

    Live geopolitical intelligence dashboard with an API and MCP server for agents

    • Remote
    • Freemium
    • Analytics and data
  5. CompanyData

    MCP server

    Search and enrich company records from official registers via the CompanyData API

    • 3 tools
    • Remote
    • Paid
    • 3 GitHub stars
    • Analytics and data
  6. ChartAnt

    MCP server

    Remote MCP server returning charts, maps and dashboards as hosted PNG links

    • 51 tools
    • Remote
    • Freemium
    • Design and media