Hybrid Recursive Ladder
Query planner that fetches long time-series ranges in a handful of requests
- 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-mcpAdd 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

Agent-Native Analytics
MCP serverOpen-source analytics app where an AI agent builds charts and dashboards from your data
- Remote
- Open source
- 7.7K GitHub stars
- Analytics and data

Google Ads + Meta Ads + SEO/GEO MCP
MCP serverHosted 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

Tapetide - Indian Stock Market MCP
MCP serverIndian NSE and BSE stock market data for AI assistants through 48 MCP tools
- 17 tools
- Remote
- Freemium
- 150 GitHub stars
- Finance and payments

World Monitor
MCP serverLive geopolitical intelligence dashboard with an API and MCP server for agents
- Remote
- Freemium
- Analytics and data

CompanyData
MCP serverSearch and enrich company records from official registers via the CompanyData API
- 3 tools
- Remote
- Paid
- 3 GitHub stars
- Analytics and data

ChartAnt
MCP serverRemote MCP server returning charts, maps and dashboards as hosted PNG links
- 51 tools
- Remote
- Freemium
- Design and media